topic Re: [newbie] how about 'hello world' in Archicad C++ API

[newbie] how about 'hello world'

Anonymous — Mon, 07 Aug 2023 10:21:30 GMT

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

Re: [newbie] how about 'hello world'

Ralph Wessel — Tue, 15 Jun 2004 20:28:06 GMT

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.

Re: [newbie] how about 'hello world'

Karl Ottenstein — Tue, 15 Jun 2004 21:35:06 GMT

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

Re: [newbie] how about 'hello world'

TomWaltz — Wed, 16 Jun 2004 00:49:32 GMT

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.

Re: [newbie] how about 'hello world'

stefan — Wed, 16 Jun 2004 06:24:31 GMT

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.

Re: [newbie] how about 'hello world'

stefan — Wed, 16 Jun 2004 07:33:27 GMT

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)

Re: [newbie] how about 'hello world'

stefan — Wed, 16 Jun 2004 12:05:55 GMT

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.

Re: [newbie] how about 'hello world'

stefan — Wed, 16 Jun 2004 12:17:45 GMT

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.

Re: [newbie] how about 'hello world'

stefan — Wed, 16 Jun 2004 12:31:32 GMT

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.

Re: [newbie] how about 'hello world'

stefan — Wed, 16 Jun 2004 12:53:35 GMT

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.

Re: [newbie] how about 'hello world'

Anonymous — Wed, 16 Jun 2004 13:27:07 GMT

Thanks for all the answers, and special thanx to stefan for his step-by-step guide

I'll work through it and see if it works the same way on the mac.

I think one of the problems is really to recognize what goes where. I mean several of the examples have, in additions to the specific addon.cpp-file, several other files like CIOStub.cpp. Those starting with APISomething I guess I shouldn't bother with, but what is the logic to what goes where, or the recommendation?

And then I wonder, an addon must include CheckEnvironment(), RegisterInterface(), Initialize() and FreeData(). But then I read about the inout module, and it said that initialization and uninitialization of Location must happen inside the main() - where do I put that, and are there more things that happen in a predefined order than the beforemensioned functions? Maybe its all to be found in the documentation, but I have been reading a lot of it, and things kind of blur...

I'm thinking of how to expand 'hello world' to explain other functions, would it be possible to read the message from a file, and log that it has been done to another file? Would it be possible to have the 'hello' appear on the plan as a textblock or maybe written by walls? - or have a pallette show up that you have to click to get the greeting?

Is it possible to interact with the database through a webbrowser using sql and a service on a webserver?

--
Regards,
Tor Jørgen

Re: [newbie] how about 'hello world'

Ralph Wessel — Wed, 16 Jun 2004 22:02:54 GMT

Tor wrote:
I'll work through it and see if it works the same way on the mac.

The process is largely the same on the Mac - the biggest differences boil down to the IDEs (CodeWarrior vs VC++). However, compiling the .grc files is much easier on the Mac. Make sure the GRC compiler and preference panels are installed in the relevant CodeWarrior plugin folders. With these installed, CodeWarrior will automatically compile the .grc files with the same simplicity as the .c/.cpp/.r files.

Tor wrote:
I think one of the problems is really to recognize what goes where. I mean several of the examples have, in additions to the specific addon.cpp-file, several other files like CIOStub.cpp. Those starting with APISomething I guess I shouldn't bother with, but what is the logic to what goes where, or the recommendation?

If you start with the example projects, you won't have to worry about this to start with. All the examples include CodeWarrior project files (.mwp), so you can be up and running quickly. As others have mentioned, you need to fill in your MDID resources to ensure the add-on will be loaded by ArchiCAD.

Files included in the project like "ACAP_STAT.lib", "DGImp.lib", etc. are library files which directly or indirectly link the functionality of the ArchiCAD API into your add-on.

You will also see CarbonLib, which is linking your add-on to Mac OS functionality. And finally, there should be C/C++ runtime libraries. I use the MSL libraries, but there is a subtle trap here. ArchiCAD add-ons must have a special compiler option set - Enums always Int - which automatically sets the size of all enumerator values to 2 bytes. Data structures in the API must be compiled this way in order for your add-on to calculate the offsets and length of the binary data in the same way as ArchiCAD. However, the standard C/C++ libraries provided with CodeWarrior have not been compiled with this option set by default, so you must build alternate versions of the libraries to use with the ArchiCAD API. If you don't, it can result in some dreadful internal inconsistencies. Let me know if you don't know how to rebuild the MSL libraries.

Tor wrote:
And then I wonder, an addon must include CheckEnvironment(), RegisterInterface(), Initialize() and FreeData(). But then I read about the inout module, and it said that initialization and uninitialization of Location must happen inside the main() - where do I put that, and are there more things that happen in a predefined order than the beforemensioned functions?

Again, use the example projects as your guide. They will no doubt demonstrate most of the functionality you intend to use. Most of the initialisation is concerned with informing ArchiCAD of the services and requirements of your add-on.

Tor wrote:
Is it possible to interact with the database through a webbrowser using sql and a service on a webserver?

To an extent, you can interact with external services by whatever protocol you wish. For example, the GBS Energy add-on we developed for GeoPraxis interacts with their server via SOAP calls. The primary limitation is that your add-on must instigate all the communication - ArchiCAD will not invoke your add-on at the request of an external service.

Re: [newbie] how about 'hello world'

stefan — Thu, 17 Jun 2004 07:14:04 GMT

vannassen wrote:
Thanks for all the answers, and special thanx to stefan for his step-by-step guide

I'll work through it and see if it works the same way on the mac. [...]
--
Regards,
Tor Jørgen

Don't forget to mail the differences back to this thread. That way, it can be a reference for others.

I am still hoping that some more experienced developers can take a quick peak at the step-by-step and see it there are things that are done completely wrong (or at least, that should have been done in a different way). They are not wrong enough to not get it working 😉

Re: [newbie] how about 'hello world'

Anonymous — Thu, 17 Jun 2004 17:57:38 GMT

I've followed Stefans guide and done the following:

I've started from scratch using the IDE of CodeWarrior which resulted in the standard framework with sourcefiles, libraries and stuff, and I've copied my ID's to the .grc-file under the MDID section.

In the RegisterInterface() I've included this line

GSErrCode errorCode = ACAPI_Register_Menu (32500, 32520, MenuCode_Tools, MenuFlag_Default);

In the Initialize() I've included this line

GSErrCode errorCode = ACAPI_Install_MenuHandler (32500, CommandHandler);

Then I've copied the CommandHandler-function from Stefans code

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

It compiled without trouble but when I registered it in ArchiCAD nothing showed up...

Then I included these lines in the .grc file

'STR#' 32500 "Menu strings" {
/*[ 1] */			"Hello World"
}

'STR#' 32501 "Strings for the Menu" {
/* [  1] */			"Hello World"
}

I've now got a menu, but when I click it nothing shows up...
What's missing?
--
Regards,
Tor Jørgen

Re: [newbie] how about 'hello world'

stefan — Fri, 18 Jun 2004 07:39:35 GMT

vannassen wrote:
Then I included these lines in the .grc file
'STR#' 32500 "Menu strings" {
/*[ 1] */			"Hello World"
}

'STR#' 32501 "Strings for the Menu" {
/* [  1] */			"Hello World"
}
I've now got a menu, but when I click it nothing shows up...
What's missing?
--
Regards,
Tor Jørgen

Try to replace 32501 with 32520 in the second STR-resource.

And try to unload and remove your add-on, close the Add-On Manager. Re-open it and reload it. And if possible, try to modify the settings for the Add-on so it's placed in the Extra-menu and not the Tools-menu. That way, you're absolutely sure that the meny will be generated all over again.

When changing menu's, I had it happen a few times that the menu in ArchiCAD was not changing, although I had the impression that the code was modified.

Re: [newbie] how about 'hello world'

Anonymous — Fri, 18 Jun 2004 08:44:38 GMT

I should have looked up the ACAPI_WriteReport function a little bit earlier - it writes to the reportwindow which I didn't view...
It has been working for a while...
I took away the 32520 string in the resouce, can't see that it did anything.

But the main thing is: I've got the 'Hello World' up and running thanx to you!
--
Regards,
Tor Jørgen

Re: [newbie] how about 'hello world'

stefan — Fri, 18 Jun 2004 08:56:20 GMT

ACAPI_WriteReport("Hello World", true) should also display a message box.

Re: [newbie] how about 'hello world'

Anonymous — Fri, 18 Jun 2004 09:24:24 GMT

I've tried both true and false, but it behaves the same.
Wonder why...
--
Regards,
Tor Jørgen

Re: [newbie] how about 'hello world'

Anonymous — Fri, 18 Jun 2004 09:56:26 GMT

Something add
A personal icona in menu


'STR#' 32500 "Menu strings" {
/* [  1] */		"Test ^32500"
}
.......

'GBMP'	32500	"Testico" {
	"Testico"
}

Icon is Testico.bmp 16x16
I am added to the \RFIX\images according to instruction, it malfunction
after added to the \Debug already compiled errorless

Re: [newbie] how about 'hello world'

Akos Somorjai — Sat, 19 Jun 2004 10:11:35 GMT

vannassen wrote:
I've tried both true and false, but it behaves the same.
Wonder why...
--
Regards,
Tor Jørgen

The behavior of ACAPI_WriteReport depends on the "Write Report" switch in Imaging and Calculation preferences. If that one is off, then the dialog won't appear even if you pass true in the second parameter. If you want an alert box which appears in every case, use DGAlert, DGResAlert, or DGResAlertParam.

Good luck,

Akos