[newbie] how about 'hello world'

[Anonymous]

When I wrote my introduction to the forum, Karl said

Looking at the PDF link that you posted, I think you're in for some "fun", Tor Jørgen! Welcome!

I'm glad for the welcome, but I worry that maybe I'm in over my head - I guess thats where the fun starts...

I'll just wait with the questions connected with my project and start really simple;

- in most of the languages I've looked at, there's always an example of how to write the simple 'hello world'-snippet. How do I do that in an addon?
- and then how does the real workprocess go, I'm thinking of debugging and setting breakpoints and beeing able to step through the code to see what happens where, and why... and how is the interaction with ArchiCAD?

--
Regards,
Tor Jørgen

[Ralph Wessel]

Tor wrote:
- in most of the languages I've looked at, there's always an example of how to write the simple 'hello world'-snippet. How do I do that in an addon?

Have you downloaded the ArchiCAD API Developer Kit yet? You will find both documentation and example projects in the kit. The example projects are mostly pretty basic, and give you an overview of what the API can do. You can use an example project as the basis for starting your own too.

Tor wrote:
- and then how does the real workprocess go, I'm thinking of debugging and setting breakpoints and beeing able to step through the code to see what happens where, and why... and how is the interaction with ArchiCAD?

You can debug, set break points, inspect variable/memory, etc. You need to set ArchiCAD as the target executable in your runtime settings so that it is launched when you 'Run' your add-on, and the build settings need to be appropriate for debugging, e.g. low optimisation. I could be more specific if you can provide a brief description of the platform you are using, e.g. OS, IDE/compiler, AC version, etc.

Regards,
Ralph.

[Karl Ottenstein]

TJ wrote:
- in most of the languages I've looked at, there's always an example of how to write the simple 'hello world'-snippet. How do I do that in an addon?

Just to add 2 cents to Ralph's excellent reply...

The equivalent to "Hello World" might be an add-on with one menu command that displays "Hello World" in the report window when the command is chosen.

You can create such an add-on as an exercise by rewriting (mostly cutting) the 3D_Test example, and 3D_Manager.c in particular which uses the WriteReport function. I'm on a deadline or I'd do it and post it ...

Regards,
Karl

[TomWaltz]

As someone who is VERY new the the Archicad API, I can tell you that a good thing to do it both to study the examples they give you with the SDK, and to try doing a File - > New Graphisoft Addon (using the templates in the SDK) to see what is actuallly *required* in any add-ons you create.

I'm just completing an add-on which is meant to ease compliance with office standards, by settings up text, dimension, & label settings (pens, sizes, fonts) and selecting a layer based on context (detail, section, or plan view, and current scale for plan view).

I have a pretty weak C/C++ background, but have done enough CAD programming that it was just a matter of knowing where to look.

I'm also on the Mac with CodeWarrior 10, so let me know if I can help.

[stefan]

As a beginning ArchiCAD-developer myself, I want to help a hand 😉

Maybe it's not too bad to do the complete process step by step, so we actually make the Hello World from scratch. But the problem is: it takes time, I did had to do some nasty things to get it running and... the API is still using Visual C++ 6.0 and we can only hope that the procedure will stay (more or less) the same in upcoming versions of ArchiCAD and the API.

I'll try to describe it in this thread (would be fun) but I expect serious "bugs" or ways-of-work. Maybe this would be the place to let it be proofread and then finalise it into a nice and clean "real" version.

[stefan]

STEP 1 : producing the correct ID's with the manager tool

On Windows, go to:
"C:\Program Files\Graphisoft\API Development Kit 5\Support\Tools\Win\AddOn Management" and start the AddOnAdmin.exe
This is the place to generate the unique Developer and Addon-ID's.

Start a New database and enter your (unique) Developer ID (something like XXXX). Once that has worked, a new XML-file has been generated which we need for the addon-ID's.

From there we can call for a "New Addon". Now you need to provide your registration code. You can type a name for the Addon and a unique LocalID will be generated.

As it happens, this "unique" local ID is not so unique: with one Developer ID you can generate 256 ID's, but a new database will generate the same ID's. In practice, unless you need to develop more then 256 Addon's, this is not a problem. During development you can reuse the same ID over & over.

(See the getting started post from Karel on this subject)

To be able to use these numbers in the development tool, you can export the database as a header file: "Save Database As..." and choose *.h

The end result of step 1:

// *****************************************************************************
// tutorial.h
//                             AddOn unique IDs 
//
// *****************************************************************************
// -----------------------------------------------------------------
// Developer: 'XXXX'
// -----------------------------------------------------------------
#define TUTORIAL_H		1234567890
// Unnamed
#define TUTORIAL_H_HelloWorld		0987654321

(Your numbers will vary, apparantly)

[stefan]

STEP 2 : creating a skeleton addon

(I'll explain it for Windows, but I guess it won't be too much different on the Mac)

In Visual Studio 6.0 you can create a new ArchiCAD Add-on with the provided wizard. Select the API DevKit folder and (optionally) add support for dialogs & input/output. We won't need them for "Hello World".

Let it generate a complete project and try to compile. It won't work!

RFIX.WIN\..\Debug\HelloWorldFix.grc.rc2 (26): error RC2104 : undefined keyword or key name: WIN_LANGUAGE_ID

Add the Developer ID

Before we solve that problem (and let me know if I do this the wrong way), we have to add the developer ID from Step 1 into the code.

Open the "HelloWorldFix.grc" file. It contains the version resource & the DevID resource. Replace the "1" and the other "1" with the ID's. Watch out, you have to add the integer and not the string for the Developer ID.
So replace the first "1" with something like 1234567890 (not the XXXX) and replace the second "1" with something like 0987654321.

As an alternative, you can include the exported database file (*.h) and use the defined ID's. It's up to you.

You won't get any feedback whatsoever if this ID is correct, though... If it is, ArchiCAD will like the Addon, if it's not, it'll only work in the demo-version of ArchiCAD.

Correct the missing keywords

This part is what I am not so sure about, but I've got it to work, so here it goes: the WIN_LANGUAGE_ID which is not recognised is actually defined in "GSLocalization.h". This file is included in the "HelloWorldFix.grc" file, which is used by the "Resource Conversion" program to generate a real resource file: "HelloWorldFix.grc.rc2".

In the localization header, we can see some info about the different language versions of ArchiCAD. I wasn't so sure how to solve it, but I tried and the following got it going: I added a few extra defines in my header files, so the included Localization file can derive the correct definitions. Inside "HelloWorld.rc2" I added a few lines like this, after the #include <Windows.h>:

#include <Windows.h>

#define INT__APP
#define INTERNAL_NAME "HelloWorld"
#define ORIGINAL_NAME "HelloWorld.apx"

#if !defined (WINDOWS)
#define WINDOWS
#endif

I guess the strings don't matter that much, but the first define made the lookup in the Localization header work.

And yes, now it compiles fine.

checking the compiled APX

Before we launch ArchiCAD, it's best to check the add-on in the Add-On Management tool. On the second tab, you can load a file (that is, the APX-file). It everything works right, it will be displayed in Green and the resource info is shown.

If it doesn't show anything, then ArchiCAD won't accept the addon, so save yourself the trouble trying.

[stefan]

STEP 3 : about Custom Build Steps

Because I wasn't able to get the provided examples compiled (maybe because I didn't follow the correct procedure in STEP 2), I was looking to the differences and there are a few.

The compilation of the resources needs some additional steps to be performed. When you look at the Project settings, you might notice the following additional "Custom Build" settings:

"HelloWorld.grc"
Description: "Compiling the localized GRC file..."
Commands: (this depends on where you installed the DevKit)
"C:\PROGRA~1\GRAPHI~1\APIDEV~1\Support\Tools\Win\ResConv.exe" -m r -D WINDOWS -T W -i RINT\HelloWorld.grc -o Debug\HelloWorld.grc.rc2 -D DEBUVERS"
Outputs:
"Debug\HelloWorld.grc.rc2"

"HelloWorld.rc2"
Description: "Compiling the RC2 file..."
Commands: (this depends on where you installed the DevKit)
"rc /i "C:\PROGRA~1\GRAPHI~1\APIDEV~1\Support\Inc" /i "C:\PROGRA~1\GRAPHI~1\APIDEV~1\Support\Modules\DGLib" /i Debug /d "DEBUVERS" /foDebug\HelloWorld.res RFIX.WIN\HelloWorld.rc2"
Outputs:
"Debug\HelloWorld.res"

"HelloWorldFix.grc"
Description: "Compiling the non-localized GRC file..."
Commands: (this depends on where you installed the DevKit)
"C:\PROGRA~1\GRAPHI~1\APIDEV~1\Support\Tools\Win\ResConv.exe" -m r -D WINDOWS -T W -i RFIX\HelloWorldFix.grc -p RFIX\Images -o Debug\HelloWorldFix.grc.rc2 -D DEBUVERS"
Outputs:
"Debug\HelloWorldFix.grc.rc2"

What these steps do is obvious: translating a non-platform-specific resource file into a platform-dependent resource file. Rather clever, but a bit complex.

A final step I like to do is directly copying the final compiled APX-file to the ArchiCAD-folder. This can be done in a Post-Build step:
"XCOPY $(TargetPath) "C:\Program Files\ArchiCAD 8.1\Goodies\" /Y"

Adapt it to where ArchiCAD is installed.

[stefan]

STEP 4 : running ArchiCAD & testing the plugin

This is easy. Load ArchiCAD, go to Tools > Add-On Manager and point to the newly created plugin: "Search for more Add-Ons..."

It'll be displayed as "API DevKit Sample" unless you modified the "HelloWorld.grc" file. Now you know why you should do this 😉

Watch out! If you have two Add-ons with the same ID, it won't load. Therefore you need to use the Add-On Management tool to generate unique ID's.

The sample does nothing... We don't have Hello World program yet!!!

STEP 5 : Finally making a Hello World program

Add the following code into CommandHandler function in the file "HelloWorld.cpp":

GSErrCode __ACENV_CALL	CommandHandler (const API_MenuParams * /*params*/)
{
	ACAPI_WriteReport ("Hello World", true);
	return NoError;
}		// CommandHandler ()

In ArchiCAD unload and reload your plugin and go to the newly entered menu Tools > Sample Menu

A warning dialog will be displayed with the famous "Hello World" text.

[stefan]

Now you should be able to try and follow along and then use the examples as reference with you.

The examples seem to all use the same "APICommon.c" and "APICommon.h" files with some useful helper functions. I included them in my add-on and had to replace "APIEnvir.h" in "APICommon.c" with "HelloWorld.hpp" at the first line so it was using my includes.