def-cg-ocx-control

Arguments: ocx-object-name-string &key doc-path use-native-size toolbar-string-or-icon toolbar-after toolbar-tooltip toolbar-help-string

This macro is supported on Windows only.

Defines a Common Graphics dialog-item class, and an associated widget-window class, for one of the OLE controls that was defined by a call to ole:def-ole-linkage. All such widgets will be subclasses of the ocx-widget class, and their widget-windows will be subclasses of the ocx-widget-window class. Methods for the Common Graphics classes that are created will be defined in the package that was defined by the ole:def-ole-linkage form.

A call to def-cg-ocx-control should be a top-level form in an application source code file, and should be placed somewhere after a call to ole:def-ole-linkage that loads the OLE application that defines the control. If the two forms are in the same file, you should place the ole:def-ole-linkage form inside an (eval-when (compile load eval) ...) form to ensure that that macro call is evaluated to create its new package before the def-cg-ocx-control form is macroexpanded (see the example at the bottom of this page). Compiling an OLE control can take a fair amount of time, so in an IDE project (for example) it is a good idea to place these forms in a project file by themselves, so that the control does not need to be recompiled whenever you modify other code in the same file.

Arguments

• ocx-object-name-string should be a string naming the particular OCX control, such as "WebBrowser" or "MonthView". Refer to the documentation for the OLE application that was loaded, or its controls, to find these names.
• doc-path: if doc-path is non-nil, then it should be a pathname or path namestring for a documentation file. Compiling (or simply macroexpanding) the def-cg-ocx-control form will generate the file with brief documentation for the control's properties, methods, and event-handler callback functions. The default is nil, in which case no documenation file is created.
• use-native-size: if use-native-size is true, then the widgets of this class will ask the OLE server for the natural size for the widget, given its current properties, and the widget will be sized accordingly. If nil, then the widget may be made any size, as with other widgets. You should pass whichever value is appropriate for the control being defined; for example, true is appropriate for the MonthView control, which always draws a calendar at a standard size, whereas nil is appropriate for the WebBrowser control, which works at any size. The default value is nil.
• toolbar-string-or-icon: if toolbar-string-or-icon is true, and the IDE is present, then a button for the new widget class will be added to the IDE's Components toolbar to allow you to place instances of the widget class onto form windows in projects. This argument is passed to add-to-component-toolbar as its pixmap-or-title argument. The default value is nil.
• toolbar-after, toolbar-tooltip, toolbar-help-string: if toolbar-string-or-icon is true (and the IDE is present), these values are passed as the values of the corresponding arguments (i.e. after, tooltip, and help-string) to add-to-component-toolbar.

Note about property names

def-cg-ocx-control will define Common Graphics properties for any OLE get and put functions that take a single argument (which is the widget itself). In the IDE inspector, you will see these properties mixed with the usual properties that are defined by Common Graphics. In a case-sensitive lisp, the standard Common Graphics properties will be entirely lowercase, while the properties provided by the OCX control will be mixed case. Sometimes there will be two properties with the same name that differ only in string case. These symbols do not conflict, even in a case-insensitive lisp, because the package that is created for the symbols that are provided by the OCX control never uses any other package and is never used by any other package. This is necessary because we cannot predict what symbol names an OCX control may use.

Note that you don't need to define the WebBrowser control, because Common Graphics defines it internally. It is exported as the cg.ie:cg-WebBrowser dialog-item class, though for this particular control it may be preferable to use the platform-independent subclass called html-widget.

Here is how Common Graphics defines the WebBrowser control. You should not evaluate this code because Common Graphics has already done so, but you could define some other OCX control similarly.

;;  Code sample for information only. It should not be
;;  evaluated by users.
;;
(eval-when (compile load eval)
  (ole:def-ole-linkage #:cg.ie :application "InternetExplorer"))

(def-cg-ocx-control "WebBrowser"
    :doc-path (merge-pathnames "WebBrowser.txt"
                               *compile-file-pathname*))

See also ole.htm.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.