CoCreate Modeling FAQ: Customization

topic end
<!--
   * Set TOPICTITLE = <nop>CoCreate Modeling FAQ: Customization
-->

---++!! CoCreate Modeling FAQ: Customization

%TOC%

<style type="text/css">
pre { background-color:#FFEECC; }
</style>

---+++ %ENGLISH% How do I customize and extend <nop>CoCreate Modeling?

In <nop>CoCreate Modeling, there are several levels of customizations:
    
   * <p>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 <nop>CoCreate Modeling.</p>
   * <p>Interactive macro definition via =Tools/Customize.../Commands/New=.</p>
   * <p>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 <nop>CoCreate Modeling or re-package existing
     functionality so that they are handier for you to use.</p>
     <p>Additionally, the Annotation module understands <nop>CoCreate Drafting
     macro language, so you can port existing <nop>CoCreate Drafting (aka
     ME10) macros with ease.</p>
     <p>Another option for programmatic extension is 
     <nop>CoCreate Modeling's .NET API.</p>

---++++ %GERMAN% Wie kann ich <nop>CoCreate Modeling anpassen und erweitern?

Es gibt in <nop>CoCreate Modeling mehrere Ebenen von Anpassungsmöglichkeiten:
    
   * <p>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.</p>
   * <p>Interaktive Definition von Makros über =Werkzeuge/Anpassen.../Commands/Neu=.</p>
   * <p>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 <nop>CoCreate Modeling
     hinzufügen oder aber bereits vorhandene Funktionalität so anpassen,
     daß sie besonders praktisch zu handhaben ist..</p>
     <p>Außerdem versteht das Modul Annotation die Makrosprache von 
     <nop>CoCreate Drafting. Damit kann man existierende Makros für
     <nop>CoCreate Drafting (früher ME10) sehr leicht portieren.
     <p>Eine weitere M&ouml;glichkeit f&uuml;r programmatische Erweiterungen
     ist das .NET API f&uuml;r <nop>CoCreate Modeling.</p>

-- Main.ClausBrod, last updated 2007/04/06

---
#IntegrationKit
<a name="ikit"></a>
---+++ %ENGLISH% What is the Integration Kit?
---+++ %ENGLISH% What is the Developer's Kit?

The Integration Kit (IKIT) is a set of APIs which can be used to extend and customize
<nop>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.

---++++ %GERMAN% Was ist das "Integration Kit"?
---++++ %GERMAN% Was ist das "Developer's Kit"?

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

Die meisten Programmierschnittstellen im IKIT sind f&uuml;r den Gebrauch
aus Lisp heraus gedacht. Die Programmierschnittstellen und die zugeh&ouml;rige
Dokumentation werden automatisch installiert; wenn man sie benutzen will,
mu&szlig; 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&uuml;tzen kann.

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

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

---

#ProgrammingDocumentation
---+++ %ENGLISH% Where do I find information and documentation about how to programmatically extend <nop>CoCreate Modeling?

Article moved [[FaqLearningLisp#ProgrammingDocumentation][here]].

---++++ %GERMAN% Wo finde ich Informationen darüber, wie man <nop>CoCreate Modeling programmatisch erweitert?

Artikel wurde [[FaqLearningLisp#ProgrammingDocumentation][verschoben]].

---
#CommandSyntax
---+++ %ENGLISH% How do I find out the syntax for a modeling command?

Use the =recorder= tool to record command sequences including all their
parameters. See [[#RecordCommandSequences][below]]. Then review the
recorded file and strip it down to the bare minimum required for your
needs. See [[MacroModelClipping][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.

---++++ %GERMAN% Wie erfahre ich die Syntax eines Modellierkommandos?

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

Au&szlig;erdem gibt es ein undokumentiertes Werkzeug, das alle Eingabeparameter
f&uuml;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.

-- Main.ClausBrod - 14 Dec 2004

---

#RecordCommandSequences
---+++ %ENGLISH% 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 <nop>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.

---++++ %GERMAN% 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 <nop>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.

-- Main.ClausBrod
---
#StartupSequence
---+++ %ENGLISH% 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 [[#ProgrammingDocumentation][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.

---++++ %GERMAN% Welche Anpassungsdateien werden beim Start in welcher Reihenfolge von <nop>CoCreate Modeling geladen?

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

-- Main.ClausBrod - 3 Jan 2005

---

---+++ %ENGLISH% How do I add my own customization code to the startup process?

<img src="%ATTACHURLPATH%/showdirectories.png" align="right" />
As indicated [[#StartupSequence][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 <nop>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.

---++++ %GERMAN% Wie füge ich beim Start von <nop>CoCreate Modeling meine eigenen Anpassungen hinzu?

Wie schon [[#StartupSequence][angedeutet]], gibt es w&auml;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
<nop>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=.

-- Main.ClausBrod - 28 Mar 2007

---
#DebugCustomizationStartup
---+++ %ENGLISH% I changed a customization file, but the changes are not picked up by <nop>CoCreate Modeling.

Maybe you are changing the wrong customization file. Unfortunately, the
flexibility which <nop>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 <nop>CoCreate Modeling 2004.
See [[#StartupSequence][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 [[OsdmFaqTroubleshooting#commandline][here]].
     Starting <nop>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.
<img src="%ATTACHURL%/console.jpg" alt="Console window logging startup process" />
   * Enter =(ui:uic-display-customization-dirs)= in the user
     input line after startup. This will tell you the directories
     which <nop>CoCreate Modeling searches for customization files during startup.
<img src="%ATTACHURL%/customizationdirs.jpg" alt="Customization directories" />
   * You'll get the same output via Edit/Settings/UI Settings/Customizations/Show Directories.

---++++ %GERMAN% Ich habe eine Anpassungsdatei ge&auml;ndert, aber die &Auml;nderungen kommen in <nop>CoCreate Modeling nicht an.

Vielleicht war es die falsche Anpassungsdatei. Leider bringt die gro&szlig;e
Flexibilit&auml;t in <nop>CoCreate Modeling bei der Konfiguration auch Komplexit&auml;t mit sich -
es gibt mehrere Stufen von Anpassungsdateien, die in verschiedenen
Verzeichnissen untergebracht werden k&ouml;nnen.

Aber zuerst zu den Grundlagen: Der _Dateiname_ der Anpassungsdatei mu&szlig;
stimmen! Zum Beispiel hat sich der Name der zentralen Anpassungsdatei von
=pesd_customize= ab <nop>CoCreate Modeling 2004 in =sd_customize= ge&auml;ndert.
Mehr zu den Dateien, die beim Start geladen werden: Siehe
[[#StartupSequence][oben]].

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

So kann man die Vorg&auml;nge w&auml;hrend der Startphase pr&uuml;fen:
   * Man verwende die Kommandozeilenoption =-v=. Details dazu werden
     [[OsdmFaqTroubleshooting#commandline][hier]] besprochen.
     Startet man <nop>CoCreate Modeling mit dieser Option, &ouml;ffnet sich ein Konsolenfenster,
     das alle Dateien, die geladen werden, mitprotokolliert. Die ge&auml;nderte
     Anpassungsdatei sollte hier auftauchen.
   * <tt>(ui:uic-display-customization-dirs)</tt>, in der Eingabezeile
     verwendet, listet die Verzeichnisse auf, die <nop>CoCreate Modeling beim Start
     nach Anpassungsdateien durchsucht.
   * Die gleiche Ausgabe bekommt man auch &uuml;ber Bearbeiten/Vorgaben/Benutzeroberfl&auml;chenvorgaben/Anpassungen/Verzeichnisse anzeigen.

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

---

#AutomaticLoad
---+++ %ENGLISH% How do I load my Lisp macro automatically when <nop>CoCreate Modeling starts?

There are various customization files which <nop>CoCreate Modeling looks for during
startup. For details, see [[#StartupSequence][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 <nop>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=:
<pre>
  (oli:sd-load-customization-file "mylispcode.lsp")
</pre>

---++++ %GERMAN% Wie lade ich mein Lisp-Makro automatisch, wenn <nop>CoCreate Modeling startet?

Es gibt verschiedene Anpassungsdateien, nach denen <nop>CoCreate Modeling beim Start sucht.
Details dazu findet man weiter [[#StartupSequence][oben]]. Die genaue
Vorgehensweise, um Makros automatisch laden zu lassen, h&auml;ngt davon ab,
welche Anpassungsdatei ausgew&auml;hlt wird.

Im folgenden nehme ich an, da&szlig; wir der Einfachheit halber
die Datei =sd_customize=
(in alten Versionen von <nop>CoCreate Modeling: =pesd_customize=) verwenden und da&szlig;
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&szlig;
     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&uuml;gen:
<pre>
  (oli:sd-load-customization-file "mylispcode.lsp")
</pre>

-- Main.ClausBrod - 3 Jan 2005

---

#UpgradeFrom11x
---+++ %ENGLISH% I just upgraded from v11.6 to <nop>CoCreate Modeling 2004 or later, and my customization files are no longer loaded.

In <nop>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 <nop>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 [[#StartupSequence][startup sequence]].

-- Main.ClausBrod - 31 Jan 2006

---

<a name="TransferToolbars"></a>
---+++ %ENGLISH% How do I transfer toolbar customizations from one system to another?

With <nop>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.

---++++ %GERMAN% Wie &uuml;bertrage ich angepa&szlig;te Werkzeugleisten von einem System zum anderen?

Ab <nop>CoCreate Modeling 2004 (v12) geht das ganz einfach - man mu&szlig; 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.

-- Main.ClausBrod - 28 Nov 2006

---

%COMMENT{type="below" nonotify="on"}%
to top
End of topic
Skip to action links | Back to top
You are here: CoCreateModeling > OsdmFaqCustomization

r1.79 - 24 Jul 2009 - 20:25 - ClausBrod to top
CoCreateModeling
Welcome
