DataViews Visual C++ Reference. DataViews for Windows Version 2.1

Transcription

1 DataViews Visual C++ Reference DataViews for Windows Version 2.1

2 GE Fanuc DataViews Headquarters 47 Pleasant Street Northampton, MA U.S.A. Telephone: (413) FAX: (413) web: GE Fanuc DataViews Japan Sales Office 16 Parale Mitsui Bldg 8 Higashida-cho Kawasaki-ku, Kawasaki Kanagawa, , Japan. Telephone: FAX: dv-japan@dvcorp.com web: GE Fanuc DataViews U.K. Sales Office Unit 1, Mill Square Featherstone Road Wolverton Mill South Miton Keynes, MK12 5BZ United Kingdom Telephone: FAX: duncan.stewart@gefanuceur.ge.com web: Copyrights and Trademarks Copyright 2000 GE Fanuc DataViews All Rights Reserved. This manual is subject to copyright protection. No portion of the contents of this book may be reproduced in any form or by any means without prior written consent from GE Fanuc DataViews. DataViews, DV-Tools, and DV-Draw are registered trademarks of GE Fanuc DataViews. DVX-Designer is a trademarks of GE Fanuc DataViews. All other trademarks are acknowledged as the property of their respective owners. October 1999 Software Release Version 2.1 Document Number Document Revision D

3 i DataViews Visual C++ Class Reference Table of Contents Chapter 1: The DataViews C++ Classes...1 DataViews Class Tables... 2 DataViews Class Maps... 4 Coordinate Systems World Coordinate System Device Coordinate System Screen Coordinate System The Display Classes CDVBlinkMgr CDVBlinkMgr Methods CDVBlinkMgr Properties CDVBaseInterface CDVBaseInterface Methods CDVBaseInterface Properties CDVBaseRuleEngine CDVBaseRuleEngine Methods CDVBaseRuleEngine Properties CDVBaseRuleEngine Events CDVBaseViewWrapper CDVBaseViewWrapper Methods CDVBaseViewWrapper Convenience Methods CDVBaseViewWrapper Events CDVBaseViewWrapper Properties CDVBaseViewWrapper Convenience Properties CDVCustomControl CDVCustomControl Methods CDVCustomControl Properties CDVCustomControl Events CDVGenericViewWrapper CDVGenericViewWrapper Methods CDVGenericViewWrapper Properties CDVGenericViewWrapper Events CDVInterface CDVInterface Methods... 62

4 ii DataViews Visual C++ Class Reference CDVInterface Properties...64 CDVInterface Events...64 CDVScrollBar...65 CDVScrollBar Methods...65 CDVScrollBar Properties...65 CDVScrollBar Events...67 CDVScrollView...68 CDVScrollView Methods...68 CDVScrollView Properties...70 CDVScrollView Events...70 CDVViewWrapper...71 CDVViewWrapper Methods...71 CDVViewWrapper Properties...72 CDVViewWrapper Events...72 CDVWinInterface...73 CDVWinInterface Methods...73 CDVWinInterface Properties...74 CDVWinInterface Events...74 CDVWinViewWrapper...75 CDVWinViewWrapper Methods...75 CDVWinViewWrapper Convenience Methods...75 CDVWinViewWrapper Properties...76 CDVWinViewWrapper Events...76 The View Class...80 CDVViewHndl...81 CDVViewHndl Methods...81 CDVViewHndl Properties The Graphical Classes CDVArcHndl CDVArcHndl Methods CDVArcHndl Properties CDVAttributes CDVAttributes Methods CDVAttributes Properties CDVAXControlHndl CDVAXControlHndl Methods CDVAXControlHndl Properties CDVAxisHndl CDVAxisHndl Methods...146

5 Table of Contents iii CDVAxisHndl Properties CDVBaseObjectHndl CDVBaseObjectHndl Methods CDVBaseObjectHndl Properties CDVBitmapHndl CDVBitmapHndl Methods CDVBitmapHndl Properties CDVCircleHndl CDVCircleHndl Methods CDVCircleHndl Properties CDVClosedSplineHndl CDVClosedSplineHndl Methods CDVClosedSplineHndl Properties CDVColorHndl CDVColorHndl Methods CDVColorHndl Properties CDVCustomAttributeHndl CDVCustomAttribute Methods CDVCustomAttrbute Properties CDVEllipseHndl CDVEllipseHndl Methods CDVEllipseHndl Properties CDVGraphHndl CDVGraphHndl Methods CDVGraphHndl Properties CDVHardwareTextHndl CDVHardwareTextHndl Methods CDVHardwareTextHndl Properties CDVLineHndl CDVLineHndl Methods CDVLineHndl Properties CDVListTicLabeller CDVListTicLabeller Methods CDVListTicLabeller Properties CDVMFCControlHndl CDVMFCControlHndl Methods CDVMFCControl Properties CDVObjectHndl CDVObjectHndl Methods

6 iv DataViews Visual C++ Class Reference CDVObjectHndl Properties CDVOpenSplineHndl CDVOpenSplineHndl Methods CDVOpenSplineHndl Properties CDVPointHndl CDVPointHndl Methods CDVPointHndl Properties CDVPolygonHndl CDVPolygonHndl Methods CDVPolygonHndl Properties CDVPolylineHndl CDVPolylineHndl Methods CDVPolylineHndl Properties CDVRectangleHndl CDVRectangleHndl Methods CDVRectangleHndl Properties CDVSubdrawingHndl CDVSubdrawingHndl Methods CDVSubdrawingHndl Properties CDVTicLabeller CDVTicLabeller Methods CDVTicLabeller Properties CDVTimeStampTicLabeller CDVTimeStampTicLabeller Methods CDVTimeStampTicLabeller Properties CDVTrueTypeAttributes CDVTrueTypeAttributes Methods CDVTrueTypeAttributes Properties CDVTrueTypeTextHndl CDVTrueTypeTextHndl Methods CDVTrueTypeTextHndl Properties CDVVarDescHndl CDVVarDescHndl Methods CDVVarDescHndl Properties CDVVariableTicLabeller CDVVariableTicLabeller Methods CDVVariableTicLabeller Properties CDVVectorAttributes CDVVectorAttributes Methods...315

7 Table of Contents v CDVVectorAttributes Properties CDVVectorTextHndl CDVVectorTextHndl Methods CDVVectorTextHndl Properties The Data Classes CDVDataSourceHndl CDVDataSourceHndl Methods CDVDataSourceHndl Properties CDVDataVarHndl CDVDataVarHndl Methods CDVDataVarHndl Properties CDVFunctionDataSourceHndl CDVFunctionDataSourceHndl Methods CDVFunctionDataSourceHndl Properties CDVFunctionDataVarHndl CDVFunctionDataVarHndl Methods CDVFunctionDataVarHndl Properties The Dynamics Classes (Rules) CDVCompareRuleCondition CDVCompareRuleCondition Methods CDVCompareRuleCondition Properties CDVControlRuleEvent CDVControlRuleEvent Methods CDVControlRuleEvent Properties CDVPickRuleCondition CDVPickRuleCondition Methods CDVPickRuleCondition Properties CDVRuleHndl CDVRuleHndl Methods CDVRuleHndl Properties CDVRuleAction CDVRuleAction Methods CDVRuleAction Properties CDVRuleCondition CDVRuleCondition Methods CDVRuleCondition Properties CDVRuleEvent CDVRuleEvent Methods CDVRuleEvent Properties

8 vi DataViews Visual C++ Class Reference CDVSetDataVarRuleAction CDVSetDataVarRuleAction Methods CDVSetDataVarRuleAction Properties CDVSimpleRuleAction CDVSimpleRuleAction Methods CDVSimpleRuleAction Properties CDVSimpleRuleCondition CDVSimpleRuleCondition Methods CDVSimpleRuleCondition Properties CDVSimpleRuleEvent CDVSimpleRuleEvent Methods CDVSimpleRuleEvent Properties CDVStringRuleAction CDVStringRuleAction Methods CDVStringRuleAction Properties CDVViewObjectRuleAction CDVViewObjectRuleAction Methods CDVViewObjectRuleAction Properties CDVViewRuleAction CDVViewRuleAction Methods CDVViewRuleAction Properties The Dynamics Classes (Thresholds) CDVArcDirectionDynamicHndl CDVArcDirectionDynamicHndl Methods CDVArcDirectionDynamicHndl Properties CDVArcDirectionThreshold CDVArcDirectionThreshold Methods CDVArcDirectionThreshold Properties CDVBasicDynamicHndl CDVBasicDynamicHndl Methods CDVBasicDynamicHndl Properties CDVBlinkDynamicHndl CDVBlinkDynamicHndl Methods CDVBlinkDynamicHndl Properties CDVBlinkThreshold CDVBlinkThreshold Methods CDVBlinkThreshold Properties CDVColorDynamicHndl CDVColorDynamicHndl Methods...382

9 Table of Contents vii CDVColorDynamicHndl Properties CDVColorThreshold CDVColorThreshold Methods CDVColorThreshold Properties CDVCurveTypeThreshold CDVCurveTypeThreshold Methods CDVCurveTypeThreshold Properties CDVDynamicFeatureHndl CDVDynamicFeatureHndl Methods CDVDynamicFeatureHndl Properties CDVDynamicFeatureSetHndl CDVDynamicFeatureSetHndl Methods CDVDynamicFeatureSetHndl Properties CDVLineStyleDynamicHndl CDVLineStyleDynamicHndl Methods CDVLineStyleDynamicHndl Properties CDVLineStyleThreshold CDVLineStyleThreshold Methods CDVLineStyleThreshold Properties CDVLineWidthDynamicHndl CDVLineWidthDynamicHndl Methods CDVLineWidthDynamicHndl Properties CDVLineWidthThreshold CDVLineWidthThreshold Methods CDVLineWidthThreshold Properties CDVOutputThreshold CDVOutputThreshold Methods CDVOutputThreshold Properties CDVPolygonPathDynamic CDVPolygonPathDynamic Methods CDVPolygonPathDynamic Properties CDVSubdrawingDynamicHndl CDVSubdrawingDynamicHndl Methods CDVSubdrawingDynamicHndl Properties CDVSubdrawingThreshold CDVSubdrawingThreshold Methods CDVSubdrawingThreshold Properties CDVTextDynamicHndl CDVTextDynamicHndl Methods

10 viii DataViews Visual C++ Class Reference CDVTextDynamicHndl Properties CDVThresholdDynamicHndl CDVThresholdDynamicHndl Methods CDVThresholdDynamicHndl Properties CDVVisibilityDynamicHndl CDVVisibilityDynamicHndl Methods CDVVisibilityDynamicHndl Properties CDVVisibilityThreshold CDVVisibilityThreshold Methods CDVSVisibilityThreshold Properties Chapter 2: C++ Header Files Introduction to the C++ Header Files Defined Constants C++ Enumerated Types DataViews C++ Public Types Miscellaneous DataViews Public Types...452

11 F:\Documentation\in_process\dataviews\common\2.1\dv_ref\frame\cpp\2_02_com_objects_cpp.fm 1 Chapter 1 1The DataViews C++ Classes 1 The DataViews C++ Class Library is a programmatic interface defining various DataViews graphical and non-graphical objects. This interface is made up of several classes, each with methods and properties, that allow you to create and manipulate DataViews objects in a Visual C++ application. Using the DataViews C++ Class Library you can display and manipulate DataViews views, work with graphical objects, and manage object data and dynamics. For more information, see DataViews Class Tables DataViews Class Maps

12 2 DataViews Visual C++ Reference DataViews Class Tables The following tables list the various class categories: The Display Classes CDVBlinkMgr CDVBaseInterface CDVBaseRuleEngine CDVBaseViewWrapper CDVCustomControl CDVGenericViewWrapper CDVInterface CDVScrollBar CDVScrollView CDVViewWrapper CDVWinInterface CDVWinViewWrapper The View Class CDVViewHndl The Graphical Classes CDVArcHndl CDVAttributes CDVAXControlHndl CDVAxisHndl CDVBaseObjectHndl CDVBitmapHndl CDVCircleHndl CDVClosedSplineHndl CDVColorHndl CDVCustomAttributeHndl CDVEllipseHndl CDVGraphHndl CDVHardwareTextHndl CDVLineHndl CDVListTicLabeller CDVMFCControlHndl CDVObjectHndl CDVOpenSplineHndl CDVPointHndl CDVPolygonHndl CDVPolylineHndl CDVRectangleHndl CDVSubdrawingHndl CDVTicLabeller CDVTimeStampTicLabeller CDVTrueTypeAttributes CDVTrueTypeTextHndl CDVVarDescHndl CDVVariableTicLabeller CDVVectorAttributes CDVVectorTextHndl The Data Classes CDVDataSourceHndl CDVDataVarHndl CDVFunctionDataSourceHndl CDVFunctionDataVarHndl The Dynamics Classes (Rules) CDVCompareRuleCondition CDVControlRuleEvent CDVPickRuleCondition CDVRuleHndl CDVRuleAction CDVRuleCondition

13 Chapter 1: The DataViews C++ Classes 3 CDVRuleEvent CDVSetDataVarRuleAction CDVSimpleRuleAction CDVSimpleRuleCondition CDVSimpleRuleEvent CDVStringRuleAction CDVViewObjectRuleAction CDVViewRuleAction The Dynamics Classes (Thresholds) CDVArcDirectionDynamicHndl CDVArcDirectionThreshold CDVBasicDynamicHndl CDVBlinkDynamicHndl CDVBlinkThreshold CDVColorDynamicHndl CDVColorThreshold CDVCurveTypeThreshold CDVDynamicFeatureHndl CDVDynamicFeatureSetHndl CDVLineStyleDynamicHndl CDVLineStyleThreshold CDVLineWidthDynamicHndl CDVLineWidthThreshold CDVOutputThreshold CDVPolygonPathDynamic CDVSubdrawingDynamicHndl CDVSubdrawingThreshold CDVTextDynamicHndl CDVThresholdDynamicHndl CDVVisibilityDynamicHndl CDVVisibilityThreshold All properties are read/write unless otherwise noted. Methods that return BOOL return FALSE on failure. Failure usually results when the method requires a view to be attached to the interface but none is.

14 4 DataViews Visual C++ Reference DataViews Class Maps The following figures illustrate the DataViews objects and their relationships to each other. Maps include: High Level DataViews Structures Map The Display Classes Map The Graphical Classes Map The Dynamics Classes (Thresholds) Map The Dynamics Classes (Rules) Map The Data Classes Map

15 Chapter 1: The DataViews C++ Classes 5 High Level DataViews Structures Map Visual C++ Application Dynamic Classes Display Classes The View Class Graphical Classes Data Classes

16 6 DataViews Visual C++ Reference The Display Classes Map CDVBaseRuleEngine CDVBaseInterface CDVBaseViewWrapper CDVWinInterface CDVWinViewWrapper creates CDVInterface CDVViewWrapper wraps CDVCustomControl or CDVSCrollView attaches CDVViewHndl

17 Chapter 1: The DataViews C++ Classes 7 The Graphical Classes Map CDVColorHndl CDVAttributes CDVTruetypeAttributes CDVVectorAttributes CDVViewHndl CDVPointHndl CDVObjectHndl CDVCustomAttributeHndl CDVBaseObjectHndl CDVPolygonHndl CDVRectangleHndl CDVLineHndl CDVPolylineHndl CDVAXControlHndl CDVHardwareTextHndl CDVVectorTextHndl CDVSubdrawingHndl CDVArcHndl CDVCircleHndl CDVEllipseHndl CDVOpenSplineHndl CDVBitmapHndl CDVMFCControlHndl CDVTrueTypeTextHndl CDVClosedSplineHndl CDVGraphHndl CDVVarDescHndl CDVAxisHndl CDVTicLabeller CDVListTicLabeller CDVVariableTicLabeller CDVTimeStampTicLabeller

18 8 DataViews Visual C++ Reference The Dynamics Classes (Thresholds) Map CDVViewHndl CDVDynamicFeatureSetHndl CDVDynamicFeatureHndl CDVThresholdDynamicHndl CDVTextDynamicHndl CDVBasicDynamicHndl CDVPolygonPathDynamicHndl CDVColorDynamicHndl CDVLineWidthDynamicHndl CDVLineStyleDynamicHndl CDVArcDirectionDynamicHndl CDVVisibilityDynamicHndl CDVSubDrawingDynamicHndl CDVBlinkDynamicHndl CDVColorThreshold CDVLineWidthThreshold CDVLineStyleThreshold CDVOutputThreshold CDVArcDirectionThreshold CDVCurveTypeThreshold CDVVisibilityThreshold CDVSubDrawingThreshold CDVBlinkThreshold

19 Chapter 1: The DataViews C++ Classes 9 The Dynamics Classes (Rules) Map CDVViewHndl CDVSimpleRuleAction CDVRuleHndl CDVRuleAction CDVRuleCondition CDVRuleEvent CDVViewRuleAction CDVViewObjectRuleAction CDVSetDataVarRuleAction CDVStringRuleAction CDVSimpleRuleCondition CDVPickRuleCondition CDVCompareRuleCondition CDVSimpleRuleEvent CDVControlRuleEvent

20 10 DataViews Visual C++ Reference The Data Classes Map CDVViewHndl CDVDataSourceHndl CDVDataVarHndl CDVFunctionDataSourceHndl CDVCustomDataSourceHndl CDVFunctionDataVarHndl CDVCustomDataVarHndl CDVDataArgHndl CDVDataArgHndl Enterprise Edition Only

21 Chapter 1: The DataViews C++ Classes 11 Coordinate Systems Some of the descriptions in this reference manual 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 Device Coordinate System Screen Coordinate System 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.

22 12 DataViews Visual C++ Reference 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. 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

23 Chapter 1: The DataViews C++ Classes 13 The Display Classes CDVBlinkMgr CDVBaseInterface CDVBaseRuleEngine CDVBaseViewWrapper CDVCustomControl CDVGenericViewWrapper CDVInterface CDVScrollBar CDVScrollView CDVViewWrapper CDVWinInterface CDVWinViewWrapper See Also: The Display Classes Map

24 14 DataViews Visual C++ Reference CDVBlinkMgr CDVBlinkMgr Methods CDVBlinkMgr Properties The Display Classes Map #include <DVBlinkMngr.h> 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 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.

25 Chapter 1: The DataViews C++ Classes 15 CDVBaseInterface CDVBaseInterface Methods CDVBaseInterface Properties The Display Classes Map #include <DVBaseInterface.h> 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 AttachViewWrapper Method DetachViewWrapper Method CheckStatus Method Draw Method DrawNext Method DrawNextObject Method DrawObject Method EnableBlink Method Erase Method EraseObject Method GetBaseRuleEngine Method GetBaseViewWrapper Method GetBounds Method GetDlgItem Method GetDataVar Method GetHREF Method GetNamedObject Method GetLocalDVPath Method GetPointCoordinates Method GetSelectedObject Method GetSelectedSubObject Method GetVariableNames Method GetView Method IsDrawn Method

26 16 DataViews Visual C++ Reference MovePoint Method OpenData Method Pan Method PanRelative Method PauseBlink Method ReadData Method Redraw Method RedrawObject Method ScreenToWorldX Method ScreenToWorldY Method TransformPoint Method TransformRectangle Method Update Method UpdateNamedObject Method WorldToScreenX Method WorldToScreenY Method ZoomPanReset Method ZoomTo Method AttachViewWrapper Method BOOL AttachViewWrapper(CDVViewHndl& vh) BOOL AttachViewWrapper(CString view_name) BOOL 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.

27 Chapter 1: The DataViews C++ Classes 17 If another view is already attached, this method calls CDVBaseViewWrapper::SetDestroyOnDetach() method automatically, so you do not have to call it explicitly. DetachViewWrapper Method DetachViewWrapper() Destroys the drawport created by CDVBaseInterface::AttachViewWrapper(). Also destroys the instance of CDVGenericViewWrapper if one was created by CDVBaseInterface::AttachViewWrapper(). Closes data sources and erases the screen automatically. 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 BOOL Draw() Performs the initial drawing of the view. Performed automatically if the DrawViewOnLoad Property is set to TRUE.

28 18 DataViews Visual C++ Reference DrawNext Method BOOL DrawNext() Draws the next iteration of data in the view. Performed automatically if AutoUpdate is set to TRUE. DrawNextObject Method BOOL 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(). DrawObject Method BOOL DrawObject(CDVObjectHndl& object) Performs the initial drawing of a specific object in the view. This method takes an object. EnableBlink Method BOOL EnableBlink( CDVObjectHndl& object, BOOL enable=true) BOOL EnableBlink(BOOL 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().

29 Chapter 1: The DataViews C++ Classes 19 Erase Method BOOL Erase() Erases the contents of the view. EraseObject Method BOOL 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. GetBaseViewWrapper Method CDVBaseViewWrapper* GetBaseViewWrapper() Returns a pointer to the CDVBaseViewWrapper class. GetBounds Method BOOL GetBounds( LONG& ll_x, LONG& ll_y, LONG& ur_x, LONG& ur_y, DV_COORD_SYSTEM = DV_WORLD_COORDS) Gets the bounding box of an object.

30 20 DataViews Visual C++ Reference 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(). 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, or by using the data source name and the variable name separately, such as default.dat and Var1. GetHREF Method static BOOL GetHREF( CString& str, CString& href) for screen coordinates for world coordinates for device coordinates 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= >, then href would then be

31 Chapter 1: The DataViews C++ Classes 21 GetLocalDVPath Method CString GetLocalDVPath() Returns the value of DVPATH for this instance. This is a combination of the base DVPATH set by the DataViews installation, and the local path prefix and suffix. Knowledge of the local path is useful when debugging applications: if the application is having trouble its views or subdrawings the problem is probably that the DVPATH is set up incorrectly. GetNamedObject Method CDVObjectHndl GetNamedObject (LPCTSTR objname) Returns the DataViews object with the specified name. This method takes the name of an object. GetPointCoordinates Method BOOL 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 GetSelectedSubObject Method CDVObjectHndl GetSelectedSubObject() const for screen coordinates for world coordinates for device coordinates Returns the sub-object underneath the last mouse motion, mouse click, or keyboard event.

32 22 DataViews Visual C++ Reference GetSelectedObject Method CDVObjectHndl GetSelectedObject() const Returns the object underneath the last mouse motion, mouse click, or keyboard event. 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 BOOL IsDrawn() const Indicates whether the view has been drawn. MovePoint Method BOOL MovePoint( CDVPointHndl& pt, LONG x, LONG y, DV_COORD_SYSTEM sys = DV_WORLD_COORDS, BOOL 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.

33 Chapter 1: The DataViews C++ Classes 23 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 BOOL OpenData () Opens the data sources for the current view. 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 of the points x and y. 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 CDVBaseInterface::ZoomTo() method. PanRelative Method BOOL PanRelative( LONG xoffset, LONG yoffset, DV_COORD_SYSTEM = DV_WORLD_COORDS) Pans the view a relative amount from its current position. for screen coordinates for world coordinates for device coordinates for screen coordinates for world coordinates for device coordinates

34 24 DataViews Visual C++ Reference The view will be panned so that the new center is (xoffset, yoffset) units from its previous center. This method takes world coordinate values by default. sys specifies the coordinate system. Valid coordinate system options are: PauseBlink Method BOOL PauseBlink(BOOL 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 BOOL ReadData() DV_SCREEN_COORDS DV_WORLD_COORDS DV_DEVICE_COORDS Reads the next iteration of data into the data source variables. For instance, the next value from a file data source. Redraw Method BOOL Redraw( const RECTANGLE* rect =NULL, DV_COORD_SYSTEM sys = DV_WORLD_COORDS, BOOL 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 DV_DEVICE_COORDS for screen coordinates for world coordinates for device coordinates 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.

35 Chapter 1: The DataViews C++ Classes 25 RedrawObject Method BOOL 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* and WorldToScreen* methods is with the zoom and pan methods. The preferred method is the TransformPoint Method on the CDVBaseInterface class. ScreenToWorldY Method LONG ScreenToWorldY(LONG x, LONG y) Converts the y component of a screen coordinate to a world value using pixels. The preferred method is the TransformPoint Method on the CDVBaseInterface class.

36 26 DataViews Visual C++ Reference TransformPoint Method BOOL TransformPoint( LONG x1, LONG y1, DV_COORD_SYSTEM sys1, LONG& x2, LONG& y2, DV_COORD_SYSTEM sys2) BOOL TransformPoint( const DV_POINT pt1, DV_COORD_SYSTEM sys1, DV_POINT& pt2 DV_COORD_SYSTEM sys2) BOOL 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

37 Chapter 1: The DataViews C++ Classes 27 TransformRectangle Method BOOL 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) BOOL TransformRectangle( const RECTANGLE& r1, DV_COORD_SYSTEM sys1, RECTANGLE& r2, DV_COORD_SYSTEM sys2) BOOL 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

38 28 DataViews Visual C++ Reference If the ReadDataOnUpdate Property is set to TRUE, this method calls CDVBaseInterface::ReadData() and then calls CDVBaseInterface::DrawNext(). If the ReadDataOnUpdate Property is set to FALSE, this method calls only CDVBaseInterface::DrawNext().If AutoUpdate is set to TRUE, this method is called in time intervals specified by the value of the UpdatePeriod Property. UpdateNamedObject Method BOOL 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 the TransformPoint Method on the CDVBaseInterface class. 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 the TransformPoint Method on the CDVBaseInterface class.

39 Chapter 1: The DataViews C++ Classes 29 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. ZoomTo Method BOOL 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 AbsoluteScaleFactor Property Anchor Property AnchorName Property AnchorRectangle Property AutoUpdate Property BlinkCheckPeriod Property ClickOnObjectFilter Property ClutFile Property CommandHandler Property DrawMode Property DrawportStretch Property DrawportType Property

40 30 DataViews Visual C++ Reference DrawViewOnLoad Property DVPathPrefix Property DVPathSuffix Property EnableBlinkOnLoad Property EnableViewResTable Property InitialScaleFactor Property InputUsedFilter Property LayerMask Property LevelOfDetail Property LineStyleMode Property MouseOverFilter Property ReadDataOnUpdate Property ReportError Property ScaleFactor Property ShowCopyright Property UpdatePeriod Property ViewResolution Property VisibilityMask Property VisibilityPriority Property AbsoluteScaleFactor Property SetAbsoluteScaleFactor(double value) double GetAbsoluteScaleFactor() Allows you to get/set the absolute scale factor of the drawport. The absolute scale factor is the number of world coordinates in the view per pixel on the screen. If views are displayed using hardware with the same resolution (pixels per inch), then the absolute scale factor is the same as view resolution. This property is useful when you are trying to position DataViews graphics relative to non-scalable bitmaps (icons). The icons will appear different physical sizes on different resolution monitors since they are a fixed number of pixels in size. If you determine that at an AbsoluteScaleFactor of 100 your graphics line up properly with all your icons, you can be sure that setting a CDVCustomControl s AbsoluteScaleFactor to 100 will make graphics continue to be aligned regardless of what hardware the view is displayed on.

41 Chapter 1: The DataViews C++ Classes 31 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.

42 32 DataViews Visual C++ Reference 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(BOOL value) BOOL GetAutoUpdate() If set to TRUE, automatic updating occurs at the interval specified by the value of UpdatePeriod. If set to FALSE, 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.

43 Chapter 1: The DataViews C++ Classes 33 ClickOnObjectFilter Property SetClickOnObjectFilter(DV_CLICK_FILTER value) DV_CLICK_FILTER GetClickOnObjectFilter() Determines whether a ClickOnObject Event is generated by a mouse click. Valid values are: Any object Named objects Name is HTML reference No objects DV_ANY_OBJECT DV_NAMED_OBJECTS DV_HREF_OBJECTS DV_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 places where the user can click (in the left column), the ClickOnObjectFilter setting (across the top), and what kind of event occurs in each case. DV_ANY_ OBJECT DV_NAMED_ 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 To turn off any reporting of ClickOnObject Events, set this filter to DV_NO_OBJECTS.

44 34 DataViews Visual C++ Reference ClutFile Property SetClutFile(LPCTSTR value) CString GetClutFile() 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. 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 DV_DRAW_MODE_COPY DV_DRAW_MODE_XOR Standard drawing is drawing the graphics onto a pixmap in preparation for displaying on the screen.

45 Chapter 1: The DataViews C++ Classes 35 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(BOOL value) BOOL GetDrawportStretch() 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. 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(BOOL value) BOOL GetDrawViewOnLoad() DV_STANDARD DV_FIXED_SCALE Specifies whether to automatically draw the view as soon as it has finished loading.

46 36 DataViews Visual C++ Reference The default is TRUE. If FALSE, 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 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. 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.

47 Chapter 1: The DataViews C++ Classes 37 EnableBlinkOnLoad Property SetEnableBlinkOnLoad(BOOL value) BOOL 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 CDVObjectHndl::EnableBlink(). The FALSE setting makes the view display faster. The default is TRUE. This property takes effect only when you draw the view. EnableViewResTable Property SetEnableViewResTable(BOOL enable) BOOL GetEnableViewResTable() const Enables or disables the view resolution table. 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.

48 38 DataViews Visual C++ Reference InputUsedFilter Property SetInputUsedFilter(DV_INPUTUSED_FILTER value) DV_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) Unnamed Input Objects Elsewhere in the View InputUsed event InputUsed event InputUsed event no InputUs ed event InputUsed event InputUsed event no InputUsed event no InputUsed event no InputUsed event InputUsed event no InputUsed event no InputUsed event no InputUsed event no InputUsed event no InputUsed event no InputUsed event

49 Chapter 1: The DataViews C++ Classes 39 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 leave the 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. LayerMask Property SetLayerMask(ULONG value) ULONG GetLayerMask() const Assists in determining if an object is visible when drawn in the view. 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.

50 40 DataViews Visual C++ Reference 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 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 on MouseOverChanged 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.