CoCreate Modeling FAQ: Customization

How do I customize and extend CoCreate Modeling?

In CoCreate Modeling, there are several levels of customizations:

• Interactive UI and settings customization: The arrangement of UI areas can be changed, i.e. you can move, dock and undock windows, the browser bar, and other UI elements. Also, you can hide und show UI elements, in particularly toolbars. Also, many of the settings you can make in dialogs are persisted automatically when you close CoCreate Modeling.

• Interactive macro definition via Tools/Customize.../Commands/New.

• Programmatic extension and customization: Our main extension language is Lisp. Using Lisp as a language and the large library of officially documented APIs in the Integration Kit, you can add new functionality to CoCreate Modeling or re-package existing functionality so that they are handier for you to use.

  Additionally, the Annotation module understands CoCreate Drafting macro language, so you can port existing CoCreate Drafting (aka ME10) macros with ease.

  Another option for programmatic extension is CoCreate Modeling's .NET API.

Wie kann ich CoCreate Modeling anpassen und erweitern?

Es gibt in CoCreate Modeling mehrere Ebenen von Anpassungsmöglichkeiten:

• Interaktive Anpassungen von Einstellungen und der Benutzeroberfläche: Elemente der Benutzeroberfläche können umarrangiert werden; so kann man beispielsweise Fenster an- und ausdocken und ebenso die Browserleiste. Man kann auch Benutzeroberflächenelemente verstecken oder zuschalten, insbesondere Werkzeugleisten. Viele der Einstellungen, die man in Dialogen machen kann, werden beim Verlassen von CoCreate Modeling automatisch abgespeichert.

• Interaktive Definition von Makros über Werkzeuge/Anpassen.../Commands/Neu.

• Programmatische Erweiterung und Anpassung: Unsere Hauptsprache zur Erweiterung ist Lisp. Benutzt man Lisp und die große Bibliothek offiziell dokumentierter Programmierschnittstellen des IKIT (Integration Kit), kann man neue Funktionalität zu CoCreate Modeling hinzufügen oder aber bereits vorhandene Funktionalität so anpassen, daß sie besonders praktisch zu handhaben ist..

  Außerdem versteht das Modul Annotation die Makrosprache von CoCreate Drafting. Damit kann man existierende Makros für CoCreate Drafting (früher ME10) sehr leicht portieren.

  Eine weitere Möglichkeit für programmatische Erweiterungen ist das .NET API für CoCreate Modeling.

-- ClausBrod, last updated 2007/04/06

---

What is the Integration Kit?

What is the Developer's Kit?

The Integration Kit (IKIT) is a set of APIs which can be used to extend and customize CoCreate Modeling. It is also sometimes called "Developer's Kit".

Most of the APIs are meant to be used from Lisp. The APIs and their documentation is installed automatically; so if you want to use the APIs, no special action is required.

If you are an application developer, there is a special IKIT license which you can acquire from CoCreate. With this license, you get a Lisp compiler and tools to protect your extensions with your own license codes.

But even if you don't buy the license, you get all of the documentation and all the APIs which you can call from (interpreted) Lisp.

Was ist das "Integration Kit"?

Was ist das "Developer's Kit"?

Das Integration Kit (IKIT) ist eine Sammlung von Programmierschnittstellen, mit denen man CoCreate Modeling erweitern und anpassen kann. Manchmal spricht man auch von "Developer's Kit".

Die meisten Programmierschnittstellen im IKIT sind für den Gebrauch aus Lisp heraus gedacht. Die Programmierschnittstellen und die zugehörige Dokumentation werden automatisch installiert; wenn man sie benutzen will, muß man also nichts Spezielles tun.

Als Anwendungsentwickler kann man auch eine spezielle IKIT-Lizenz von CoCreate erwerben. Mit dieser Lizenz bekommt man einen Lisp-Compiler und Werkzeuge, mit denen man seine Erweiterungen mit eigenen Lizenzcodes schützen kann.

Aber auch ohne diese spezielle Lizenz bekommt man die komplette IKIT-Dokumentation und die Möglichkeit, alle API-Aufrufe des IKITs aus (interpretiertem) Lisp-Code heraus zu benutzen.

-- ClausBrod - 07 Jun 2005, last updated 2007/04/06

---

Where do I find information and documentation about how to programmatically extend CoCreate Modeling?

Article moved here.

Wo finde ich Informationen darüber, wie man CoCreate Modeling programmatisch erweitert?

Artikel wurde verschoben.

---

How do I find out the syntax for a modeling command?

Use the recorder tool to record command sequences including all their parameters. See below. Then review the recorded file and strip it down to the bare minimum required for your needs. See the macro section for an example which explains the steps.

There is also an undocumented tool to list all input parameters for a number of commands: Enter (oli:sd-online-reference) in the user input line. This will add a new entry "Online Reference" to the toolbox which will list dialogs along with their type and parameters.

Wie erfahre ich die Syntax eines Modellierkommandos?

Um Kommandofolgen inklusive aller Parameter aufzuzeichnen, bietet sich das Rekorder-Tool an - siehe unten. Die aufgezeichnete Datei untersucht man dann näher und kürzt sie auf ein Minimum, bis nur noch die Kommandos von Interesse enthalten sind. Siehe auch den Abschnitt zur Makro-Programmierung - dort findet sich ein Beispiel mit genauerer Erläuterung der Schritte.

Außerdem gibt es ein undokumentiertes Werkzeug, das alle Eingabeparameter für eine Auswahl von Befehlen anzeigt: (oli:sd-online-reference) in der Eingabezeile eingeben, und schon hat man in der Werkzeugkiste einen neuen Eintrag namens "Online Reference", der Dialogkommandos, ihren Typ und ihre Parameter auflistet.

-- ClausBrod - 14 Dec 2004

---

How can I record command sequences and turn them into a macro?

You can define a macro interactively via Tools/Customize.../Commands/New. This is a great way to very easily assign a command sequence to a toolbar button, so that you can re-run it anytime by clicking on that button.

You can also use the low-level recorder tool. To load the tool, enter (load "recorder") (Windows) or (load "goodies/recorder") (HP-UX). This will add a new entry into the toolbox (Tools/Toolbox) from where you can record command sequences or load prerecorded sequences.

When should you use which of those tools?

Interactive macro definition is most useful for short command sequences which you want to assign directly to a toolbar button. The recorder tool, however, can be used for longer sequences, usually to learn something about internal CoCreate Modeling commands or in preparation for writing a real and full-blown Lisp-based macro. In this case, the recorder output is only the raw material for subsequent customization and programming efforts.

Wie kann ich Kommandofolgen aufzeichnen und in Makros verwandeln?

Makros kann man interaktiv über Werkzeuge/Anpassen.../Commands/Neu definieren - eine sehr gute Methode, um ganz einfach einem Knopf in einer Werkzeugleiste eine Kommandofolge zuzuweisen, die man dann jederzeit wieder auf Knopfdruck ablaufen lassen kann.

Man kann aber auch den etwas bodenständigeren recorder einsetzen. Um dieses Werkzeug zu laden, gibt man (load "recorder") (Windows) oder (load "goodies/recorder") (HP-UX) ein. Es erscheint dann unter Werkzeuge/Werkzeugkiste ein neuer Eintrag, von dem aus man Kommandofolgen mitschneiden oder aber vorher aufgenommende Sequenzen wieder abspielen kann.

Wann verwendet man welches Werkzeug?

Die interaktive Methode ist besonders nützlich für kurze Kommandofolgen, die man mal schnell einer Werkzeugleiste hinzufügen will, ohne an der Kommandofolge große Modifikationen zu machen. Der Rekorder hingegen bietet sich für längere Kommandofolgen an, die man beispielsweise aufzeichnet, um etwas über die internen Kommandos von CoCreate Modeling zu lernen oder das Schreiben eines längeren Makros vorzubereiten. In diesem Fall liefert die Ausgabe des Rekorders nur das Rohmaterial für folgende Anpassungen und Programmierarbeiten.

-- ClausBrod

---

Which customization files are loaded during startup, and in which sequence?

A thorough discussion on which files are loaded when can be found in the online documentation on Advanced Customization: Follow the instructions above on how to get to the "Customization Guide". Then scroll down to "Customization Guide for Administrators and Advanced Users"; follow the link, then click on "Filenames and Directories" in the table of contents.

Welche Anpassungsdateien werden beim Start in welcher Reihenfolge von CoCreate Modeling geladen?

Eine gründliche Abhandlung darüber, welche Dateien wann geladen werden, kann man in der Online-Dokumentation zu "Advanced Customization" finden: Man folge den obigen Anweisungen, um zum "Customization Guide" zu gelangen. Dann blättert man vorwärts bis "Customization Guide for Administrators and Advanced Users", folgt dem Verweis und klickt dann im Inhaltsverzeichnis auf "Filenames and Directories".

-- ClausBrod - 3 Jan 2005

---

How do I add my own customization code to the startup process?

As indicated above, the startup sequence provides several opportunities for customization code to be loaded and integrated automatically. The most common option is to create a file called sd_customize and place it into one of the customization directories which CoCreate Modeling automatically searches during startup.

To find out which directories those are, open the "UI Settings" dialog (Edit/Settings/UI Settings), then click the "Customizations" tab. You can now display the customization directories by clicking "Show Directories".

Most of the time, you will want to add your customizations to the "User Customization Directory", so simply move your sd_customize file there.

sd_customize is loaded after the main application has been initialized, but before add-on modules such as Annotation is loaded. Hence, sd_customize can contain arbitrary commands in Lisp syntax, but only for functionality which is already available at this point. For Annotation customization, am_customize is the right file to create and/or modify.

Wie füge ich beim Start von CoCreate Modeling meine eigenen Anpassungen hinzu?

Wie schon angedeutet, gibt es während des Startvorgangs mehrere Gelegenheiten, Anpassungscode automatisch zu laden und zu integrieren. Am üblichsten ist es, eine Datei namens sd_customize zu erzeugen und sie in einem der Anpassungsverzeichnisse abzulegen, die CoCreate Modeling beim Start automatisch durchsucht.

Welche Verzeichnisse sind das? Um das herauszufinden, öffnet man den Dialog "Benutzeroberflächenvorgaben", klickt dann auf den Reiter "Anpassungen". Jetzt kann man die Anpassungsverzeichnisse anzeigen lassen, indem man auf "Verzeichnisse anzeigen" klickt.

Meistens wird man wohl Anpassungen in das "Benutzer-Anpassungsverzeichnis" hinzufügen - legen Sie Ihre Datei sd_customize also einfach dort ab.

sd_customize wird geladen, nachdem die Applikation initialisiert ist, aber noch bevor Zusatzmodule wie Annotation geladen werden. Daher kann sd_customize beliebige Kommandos in Lisp-Syntax enthalten, aber nur für Funktionalität, die zu diesem Zeitpunkt bereits geladen ist. Will man Annotation anpassen, dann ist am_customize die richtige Datei, nicht sd_customize.

-- ClausBrod - 28 Mar 2007

---

I changed a customization file, but the changes are not picked up by CoCreate Modeling.

Maybe you are changing the wrong customization file. Unfortunately, the flexibility which CoCreate Modeling provides in the customization area comes at the price of increased complexity - there are multiple levels of customization files, which can be deployed in multiple directories.

But first the basics: Make sure that the filename of the customization file is correct. For instance, the old central customization file pesd_customize changed its name to sd_customize with the release of CoCreate Modeling 2004. See above to learn which startup files are loaded and when.

Make sure to check the settings of environment variables which influence the startup procedure, such as SDUSERCUSTOMIZEDIR or SDCORPCUSTOMIZEDIR. (Simply look for all environment variables which start with SD.)

To debug the startup process, try the following:

• Use the command-line option -v. The details are discussed here. Starting CoCreate Modeling with this option opens a console window whichs logs all files which are loaded. Check if the customization file which you modified shows up in the listing.

• Enter (ui:uic-display-customization-dirs) in the user input line after startup. This will tell you the directories which CoCreate Modeling searches for customization files during startup.

• You'll get the same output via Edit/Settings/UI Settings/Customizations/Show Directories.

Ich habe eine Anpassungsdatei geändert, aber die Änderungen kommen in CoCreate Modeling nicht an.

Vielleicht war es die falsche Anpassungsdatei. Leider bringt die große Flexibilität in CoCreate Modeling bei der Konfiguration auch Komplexität mit sich - es gibt mehrere Stufen von Anpassungsdateien, die in verschiedenen Verzeichnissen untergebracht werden können.

Aber zuerst zu den Grundlagen: Der Dateiname der Anpassungsdatei muß stimmen! Zum Beispiel hat sich der Name der zentralen Anpassungsdatei von pesd_customize ab CoCreate Modeling 2004 in sd_customize geändert. Mehr zu den Dateien, die beim Start geladen werden: Siehe oben.

Die Werte von Umgebungsvariablen, die die Startphase beeinflussen, sollte man ebenfalls überprüfen, also beispielsweise SDUSERCUSTOMIZEDIR oder SDCORPCUSTOMIZEDIR. (Am einfachsten sucht man einfach alle Umgebungsvariablen, die mit SD anfangen.)

So kann man die Vorgänge während der Startphase prüfen:

• Man verwende die Kommandozeilenoption -v. Details dazu werden hier besprochen. Startet man CoCreate Modeling mit dieser Option, öffnet sich ein Konsolenfenster, das alle Dateien, die geladen werden, mitprotokolliert. Die geänderte Anpassungsdatei sollte hier auftauchen.
• (ui:uic-display-customization-dirs), in der Eingabezeile verwendet, listet die Verzeichnisse auf, die CoCreate Modeling beim Start nach Anpassungsdateien durchsucht.
• Die gleiche Ausgabe bekommt man auch über Bearbeiten/Vorgaben/Benutzeroberflächenvorgaben/Anpassungen/Verzeichnisse anzeigen.

-- ClausBrod - 29 Dec 2004, last updated 1 Feb 2006

---

How do I load my Lisp macro automatically when CoCreate Modeling starts?

There are various customization files which CoCreate Modeling looks for during startup. For details, see above. The exact procedure to have your code automatically loaded depends on which of the customization files is most appropriate for your purpose.

In the following, I will assume for simplicity that we will use the sd_customize file (pesd_customize in old versions of CoCreate Modeling), and that your Lisp code is in mylispcode.lsp.

• Locate the sd_customize file which you want to use for "registering" your Lisp code, or create a new one in one of the directories which are searched during startup.
• Copy mylispcode.lsp to the same directory.
• Add the following line to sd_customize:

  (oli:sd-load-customization-file "mylispcode.lsp")

Wie lade ich mein Lisp-Makro automatisch, wenn CoCreate Modeling startet?

Es gibt verschiedene Anpassungsdateien, nach denen CoCreate Modeling beim Start sucht. Details dazu findet man weiter oben. Die genaue Vorgehensweise, um Makros automatisch laden zu lassen, hängt davon ab, welche Anpassungsdatei ausgewählt wird.

Im folgenden nehme ich an, daß wir der Einfachheit halber die Datei sd_customize (in alten Versionen von CoCreate Modeling: pesd_customize) verwenden und daß der neue Lisp-Code in der Datei mylispcode.lsp gespeichert ist.

• Die Datei sd_customize auffinden, die man zum "Registrieren" des eigenen Lisp-Codes verwenden will. Eventuell muß man erst in einem Verzeichnis, das beim Start abgesucht wird, eine eigene solche Datei anlegen.
• Die Datei mylispcode.lsp in das gleiche Verzeichnis kopieren.
• Die folgende Zeile zu sd_customize hinzufügen:

  (oli:sd-load-customization-file "mylispcode.lsp")

-- ClausBrod - 3 Jan 2005

---

I just upgraded from v11.6 to CoCreate Modeling 2004 or later, and my customization files are no longer loaded.

In CoCreate Modeling 2004, the names of some customization files changed to make the whole customization story more logical and simpler to use. The fundamental customization approach (corp/site/user) did not change.

For details, review the document "Upgrade Guide from CoCreate Modeling 11.x" under "Customization" in the online help viewer. You might also want to read the "Customization Guide for Administrators and Advanced Users", also available in the online help information.

See also the notes above on the startup sequence.

-- ClausBrod - 31 Jan 2006

---

How do I transfer toolbar customizations from one system to another?

With CoCreate Modeling 2004 (v12) and later, customizations can be transferred simply by copying a few customization files. In earlier versions, customization data were held in the registry which made it a little trickier to access them. See http://www.cocreate.com/CoCreatenews/March04/Tips&Tricks_Successful_toolbar_customizations_part1.pdf and http://cocreateusers.org/forum/showthread.php?t=5083 for some hints.

Wie übertrage ich angepaßte Werkzeugleisten von einem System zum anderen?

Ab CoCreate Modeling 2004 (v12) geht das ganz einfach - man muß nur ein paar Anpassungsdateien kopieren. In den Versionen davor wurden Anpassungsdaten in der Registry gesichert, was den Zugriff ein wenig kniffliger machte. Weitere Hinweise unter http://www.cocreate.com/CoCreatenews/March04/Tips&Tricks_Successful_toolbar_customizations_part1.pdf und http://cocreateusers.org/forum/showthread.php?t=5083.

-- ClausBrod - 28 Nov 2006

---

When asked for a TWiki account, use your own or the default TWikiGuest account.