The features described in this topic are obsolete
and should not be used in new IDL code.
Methods
In ActiveX terminology, methods are special statements that execute on behalf of an object in a program. For example, the ExecuteStr method can be used to execute an IDL statement, function, or procedure when the user clicks on a button in a Visual Basic program. The syntax of a method statement is:
where
- Object is the name of an object you want to control, for example an IDLDrawWidget.
- Method is the name of the method you want to execute.
- Value is an optional parameter used by the method. The various methods to the IDLDrawWidget may require zero, one, or multiple parameters.
Note
When a method returns a BOOL, the value TRUE is equal to 1 and FALSE is equal to 0.
CopyNamedArray
This method copies an IDL array to an OLE Variant array.
Parameters
BSTR: The name of the array variable that you wish to copy.
Returns
VARIANT: Reference to the array.
Remarks
This function returns an array reference that is local to the calling function. Attempting to use this array outside the calling function could result in runtime errors.
CopyWindow
This method copies the contents of the IDLDrawWidget window to the Windows clipboard.
Parameters
None.
Returns
BOOL: TRUE if successful.
CreateDrawWidget
This method creates an IDLDrawWidget in an ActiveX control frame. When you drag and drop the IDLDrawWidget, you are creating the frame that will contain the actual draw widget. Drawing operations to the control cannot be made until this method is called.
Parameters
None.
Returns
LONG: The widget ID of the created draw widget or -1 in the event of an error.
DestroyDrawWidget
This method destroys the IDLDrawWidget, but not the ActiveX control frame.
Parameters
None.
Returns
None.
DoExit
This method exits the ActiveX control and frees any resources in use by IDL.
After all IDL ActiveX control use is complete, but before the EDE application exits, you must call DoExit to allow the ActiveX control to shutdown IDL gracefully and free any resources in use.
Parameters
None.
Returns
None.
Remarks
In spite of the name, DoExit is not one of the IDL ActiveX control auto events. Like InitIDL, DoExit should be called once and only when you are exiting the EDE application.
Warning
Once DoExit is called, you are not allowed to call methods or set properties within the IDL ActiveX control from the currently running EDE application, regardless of which IDLDrawWidget the method was called on. Attempting to do so will result in a runtime error subsequently causing the EDE application to crash.
ExecuteStr
This method passes a string to IDL which IDL then executes.
Parameters
BSTR: A string containing the command that IDL will execute.
Returns
LONG: 0 if successful or the IDL error code if it fails.
Remarks
Most IDL commands that are executed with ExecuteStr run in the main level.
GetNamedData
This method returns the IDL data value associated with the named variable.
Parameters
BSTR: A string containing the name of an IDL variable.
Returns
VARIANT: Returns the value of the requested data. The type will be EMPTY if the IDL variable doesn't exist.
Remarks
The following table lists the supported IDL data types and the corresponding VARIANT data types.
InitIDL
This method initializes IDL. IDL only needs to be initialized once for each instance of the ActiveX control.
Parameters
LONG: InitIDL is called with the hWnd of the main window for the container application. If this value is null, the ActiveX control uses the hWnd of the ActiveX control frame.
Returns
LONG: Long value indicating status of IDL
|
Value
|
Meaning
|
|---|---|
|
|
Successful |
|
|
Failure |
|
|
IDL ActiveX control is not licensed |
|
|
IDL is unlicensed (demo) |
If your application contains more than a single IDLDrawWidget (e.g., IDLDrawWidget1 and IDLDrawWidget2), the InitIDL method should only be called on one of the objects, not both.
The IDL ActiveX control relies on IDL and must, at a minimum, have an IDL runtime distribution to operate successfully. The IdlPath property can be set so the control can find a valid IDL distribution (the idl.dll). If a valid distribution is not found in either the path as set in the IdlPath property or the current directory, a dialog will be displayed giving the user the opportunity to specify the location of his IDL distribution. This behavior may be overridden at runtime by locating and specifying the path to the IDL distribution prior to calling either the InitIDL or SetOutputWnd methods.
InitIDLEx
This method initializes IDL. It is identical to the InitIDL method except that it has an additional parameter, Flags, allowing initialization flags to be passed on to IDL. See the description of the InitIDL for details on the return value.
Parameters
LONG: InitIDL is called with the hWnd of the main window for the container application. If this value is null, the ActiveX control uses the hWnd of the ActiveX control frame.
LONG: Flags. A bitmask used to specify initialization options. The allowed bit values are:
Returns
LONG: Long value indicating status of IDL. See the description of the return value under InitIDL for details.
This method prints the contents of the ActiveX control to the current default printer for both Direct and Object Graphics windows. The Print method will print the contents of a Direct Graphics window at screen resolution (72-96 dpi). For information about controlling print resolution of an object graphics window, see the BufferId property.
Note
In order to print the contents of an Object Graphics window, you must associate the IDL graphics tree (an IDLgrView object) with the IDLgrWindow object used by the underlying draw widget. Do this by setting the GRAPHICS_TREE property of the IDLgrWindow object to the IDLgrView object:;Retrieve the window object associated with the draw widget.
IDLDrawWidget::ExecuteStr("Widget_Control, IDLDrawWidget, $
Get_Value =oWindow");
;Set the Graphics_Tree property to the view object.
IDLDrawWidget::ExecuteStr("oWindow->SetProperty, $
Graphics_Tree = oView");
Parameters
XOffset: The X offset to print the graphic in 0.01 of a millimeter.
YOffset: The Y offset to print the graphic in 0.01 of a millimeter.
Width: The desired width of the printed graphic in 0.01 of a millimeter.
Height: The desired height of the printed graphic in 0.01 of a millimeter.
The X offset plus the width should be less than or equal to the width of a single page. The Y offset plus the height should be less than or equal to the height of a single page. The origin of the offset 0,0 is in the upper left corner of a page. If these values are set to 0, the ActiveX control will print a graphic in the upper left corner of the page with the size of the graphic approximating the size of the image on the screen.
Returns
BOOL: TRUE if printing succeeded.
RegisterForEvents
This method causes IDLDrawWidget to pass the specified events to the application. These events only apply if the user hasn't set the corresponding auto event property.
Parameters
LONG: Flags that indicate which events you wish to forward to your application. Values can be combined if multiple events are desired.
|
Value
|
Meaning
|
|---|---|
|
|
Stop forwarding all events |
|
|
Forward mouse move events |
|
|
Forward mouse button events |
|
|
Forward view scrolled events |
|
|
Forward expose events |
Note
Motion events may be generated continuously in response to certain operations in IDL. As a result, if you forward mouse move events, your event handler should check the reported position of the mouse to determine whether it has in fact moved before doing extensive processing.
Returns
BOOL: TRUE if successful.
SetNamedArray
This method creates a named IDL array with the specified data. The data pointer is shared with IDL and the EDE application. Thus, changes in either IDL or the EDE will be reflected in both.
Parameters
BSTR: Name of array variable to create in IDL.
VARIANT: Array data to be shared with IDL.
BOOL: True if IDL should free a shared array when IDL releases its reference, false if not.
Returns
WORD: 1 if successful, 0 if set failed.
Remarks
Because SetNamedArray creates an array whose data is shared between IDL and the EDE application, IDL constructs that could change the type and/or dimensionality of the array must be avoided, as these constructs could have the side effect of creating a new array in IDL and thus breaking the shared link.
The array parameter of SetNamedArray must have a lifetime beyond the calling function. Thus, in Visual Basic, it is recommended that the array be declared as global in scope to prevent runtime errors from occurring.
Note
In order to allow data to be shared between IDL and the external environment, the lock count on the underlying array is incremented. Some external environments, notably later versions of Delphi, do not allow array locking to extend beyond a single method call and will signal an error when SetNamedArray returns. If this occurs, the data cannot be shared between IDL and the external environment using SetNamedArray. Use the SetNamedData method to insert a copy of the array into IDL.
The following table lists the accepted variant types and the corresponding IDL types.
SetNamedData
This method creates an IDL variable with the specified name and value. Both the EDE and IDL maintain their own copy of the data. SetNamedData can also be used to change the value of an existing IDL variable.
Parameters
BSTR: Name of the variable to create in IDL.
VARIANT: Data to be copied in IDL.
Returns
WORD 1 if successful.
SetOutputWnd
This method sends output from IDL to the specified window.
Parameters
HWND: The hWnd of the edit control that will receive the output.
Returns
None.
Note
SetOutputWnd is the only method that can be called prior to a call to InitIDL.
VariableExists
This method determines if a specified variable is defined in IDL.
Parameters
BSTR: Name of variable to check.
Returns
BOOL:TRUE if variable is defined in IDL at the main level. False if the variable is not defined.
