スタートガイド

　

スタートガイド

ここでは、ゼロから Archicadアドオンを作成する方法を紹介します。

Archicadアドオンの基本

Archicadアドオンのプログラミング言語はC/C++ なので、この言語に慣れていないと始められません。
Archicadは様々な方法で拡張することができます：

  • 新しいメニューコマンド
  • ダイアログの作成
  • インポート・エクスポート機能

API自体は汎用的なものなので、同じ開発キットを使って様々なアドオンを書くことができます。

何が必要ですか？

まずは、開発環境を整える必要があります。

  • 開発者登録 – まずはGRAPHISOFT IDの作成、および開発者登録を行います。登録は無料です。

  • Archicad – デモバージョンでもAPIを試すのに全く問題ありませんが、開発過程で経験するかもしれないいくつかの制限があります。

  • API Development Kit – これにより、あなたのコンピュータ上で Archicad アドオンをビルドすることができます。

  • IDE – お使いのプラットフォームに応じて、開発環境が必要です。Windows では Microsoft Visual Studio、MacOS では Xcode が必要になります。Archicadバージョンに応じた開発環境を使用する必要がありますので、詳細は以下の表をご覧ください。
Windows MacOS
Archicad 23 Visual Studio 2017 (v141 ツールセット) 最新の Xcode (デプロイメントターゲット macOS 10.12)
Archicad 24 Visual Studio 2017 (v141 ツールセット) 最新のXcode (デプロイメントターゲットmacOS 10.13)
Archicad 25 Visual Studio 2019 (v142 ツールセット) 最新の Xcode (デプロイメントターゲット macOS 10.15)

API開発キットの構成

Development Kitをインストールした後、インストール先に3つのフォルダがあります。

  • Documentation: APIのドキュメント用のフォルダです。ここには、すべてのAPI機能のリファレンスが記載されています。このドキュメントはオンラインでも利用可能です。

  • Examples: ここには、たくさんのアドオンの例があります。APIがどのように動作するかを理解するための良い出発点となります。プロジェクトを開いて、その可能性を試して見てください

  • Support:アドオン開発のためのすべてのヘッダーとライブラリファイル、およびリソースのコンパイル用ツールが含まれています。アドオンをビルドする際に必要となるフォルダです。

最初のアドオンをビルドしよう

サンプルのアドオンから始めることもできますが、プロジェクトテンプレートから始める方法をご紹介します。Archicad アドオンのテンプレートはDevelopment Kitと一緒にインストールされています。

1. アドオンのための IDE プロジェクトを生成する

まずはアドオンテンプレートからIDEプロジェクトを生成します。

Visual Studioの場合

次の場所にテンプレートが表示されます。
テンプレートプロジェクトはインクルード先が相対パスであらかじめ指定されています。そのためまずはDevelopment Kitの中にフォルダを作成しそこをプロジェクトの保存先に指定します。

Xcodeの場合

次の場所にテンプレートが表示されます。プロジェクトの保存先は任意の場所で問題ありません。

2. アドオンのビルド

IDEプロジェクトを生成したら、それを開きビルドを実行してください。すべてがうまくいくと、エラーや警告は表示されず、結果フォルダに .apx ファイル (Windows) / .bundle (macOS) が作成されます。

3. デモモードでArchicadを起動する

テンプレートから作成したアドオンやサンプルのアドオンはArchicadのデモモードでのみ動作することに注意してください。デモモード以外でアドオンを使用するにはMDIDを登録する必要があります (詳細はアドオンのリリースの章を参照してください)。
デモモードでArchicadを起動するために、次のように実行ファイルにコマンドラインパラメータを渡します。

Windows の場合

Archicad.exe -DEMO

ショートカットを作成して同様のパラメータを渡すことで、デモモードで起動することが可能です

Mac の場合

"ARCHICAD 24.app/Contents/MacOS/ARCHICAD" -demo

4. Archicad でアドオンを試す

Archicad でアドオンを読み込むにはいくつかの方法があります。開発目的のためには、ビルドフォルダを直接参照するのが簡単な方法で、すべての修正がすぐに Archicad に表示されます。

  1. オプション / アドオンマネージャ を選択して アドオンマネージャ ダイアログを開きます。
  1. 「使用可能なアドオンのリストを編集」タブページの「追加」ボタンをクリックします。
  1. アドオンの.apx/.bundleファイルを参照し、問題がなければアドオンの一覧に表示されます。
  1. アドオンマネージャを閉じると、アドオンに登録された新しいコマンドが表示されます：「オプション」/「アドオンコマンドの例」。

おめでとうございます！あなたは最初のArchicad アドオンを作成しました。

何か動作しませんか？

時々、以下のようなエラーメッセージが表示されることがあります。これは、アドオンのロードプロセス中にエラーが発生したことを意味します。この問題にはいくつかの理由が考えられますが、以下をご覧ください。

無効なMDID

テンプレートから作成したアドオンやサンプルのアドオンは Archicadのデモモードでのみ動作することに注意してください。あなたのアドオンをリリースするには MDID を登録する必要があります (詳細はアドオンのリリースの章を参照してください)。

無効な開発キットバージョン

Archicadは、異なるバージョンの開発キットでアドオンが作成された場合、そのアドオンを読み込むことができません。Archicadのバージョンと使用されたDevelopment Kitのバージョンが同じかどうか再確認してください。

アドオンの構造

アドオンフォルダには、いくつかのサブフォルダがあります。

Add-On のソース

アドオンのソースコードはSrcフォルダにあります。

Add-Onには4つの重要なエントリーポイントがあります。

  • CheckEnvironment: この関数は、他の関数の前に呼び出されます。あなたのアドオンが現在の環境で実行できるか、または許可されているかどうかを確認できます。また、Add-Onの名前と説明を提供する必要があります。この情報は、アドオンマネージャに表示されます。

  • RegisterInterface:この関数は、Archicadのインターフェース要素（メニューコマンド、ツールボックスアイテムなど）を登録する役割を果たします。

  • Initialize: この関数は、アドオンがメモリにロードされたときに、アドオンの機能を実行する前に呼び出されます。

  • FreeData: この関数は、Add-On がメモリからアンロードされるときに呼び出されます。
    これらの関数についての詳細な説明は、こちらをご覧ください。

API_AddonType __ACDLL_CALL CheckEnvironment (API_EnvirParams* envir)
{
    RSGetIndString (&envir->addOnInfo.name, ID_ADDON_INFO, 1, ACAPI_GetOwnResModule ()) を実行します。
    RSGetIndString (&envir->addOnInfo.description, ID_ADDON_INFO, 2, ACAPI_GetOwnResModule ()) を実行します。
 
    return APIAddon_Normal;
}
 
GSErrCode __ACDLL_CALL RegisterInterface (void)
{
    return ACAPI_Register_Menu (ID_ADDON_MENU, 0, MenuCode_Tools, MenuFlag_Default);
}
 
GSErrCode __ACENV_CALL Initialize (void)
{
    return ACAPI_Install_MenuHandler (ID_ADDON_MENU, MenuCommandHandler);
}
 
GSErrCode __ACENV_CALL FreeData (void)
{
    return NoError;
}

アドオンのリソース

リソースのソースコードはそれぞれ次の通りです。

  • RFIX：画像などのローカライズされていないリソースを修正します。
  • RFIX.mac、RFIX.win: プラットフォーム依存のユーティリティコード。
  • RINT: ローカライズされるリソースです。
  • ツール リソースビルドツール

ArchicadアドオンはWindowsとmacOSの両方のプラットフォームで動作します。そのため、ローカライズされた文字列やダイアログのためにネイティブのリソースファイルを使用することはできません。これが、両方のプラットフォームで動作するプラットフォームに依存しないリソース記述形式である.grc形式を使用する理由です。つまり、リソースを定義するのは一度だけで、あとはコードを修正することなく両方のプラットフォームで動作させることができます。

リソースの日本語対応

テンプレートから作成したプロジェクトやサンプルプロジェクトでは、リソースに日本語を使用できません。日本語に対応するためには、リソースファイルのプロパティ設定を次のように変更する必要があります。

.grc、 Fix.grc

  • -T W の後に -c 0 を追加
  • 1252をutf8に変更

変更前：

"..\..\..\Support\Tools\Win\ResConv.exe" -m r -D WINDOWS -T W -q utf8 1252...

変更後：

"..\..\..\Support\Tools\Win\ResConv.exe" -m r -D WINDOWS -T W -c 0 -q utf8 utf8...

.rc2

  • rc の後に/c65001を追加

変更前：
rc /i "..\..\..\Support\Inc

変更後：
rc /c65001 /i "..\..\..\Support\Inc

動作確認方法

それぞれのファイルをコンパイルして問題がなければ、変更は正しく行われています。

デバッグ

デバッグはとても簡単で次の2つの方法があります。

  • 実行中のArchicadプロセスにデバッガをアタッチするだけで、他のアプリケーションのように Add-On をデバッグすることができます。
  • プロセスをよりスムーズにするために、アドオンプロジェクトの実行デバッグコマンドとして Archicadを設定し、デバッグを押すだけでArchicadを起動することもできます。

アタッチ

デバッグコマンド

Visual Studio のヒント

Archicadのプロセスにアタッチする際、ダイアログの「アタッチ先」項目で”ネイティブコード”が選択されていることを確認してください。また、アドオンがメモリにロードされるまでブレークポイントが有効にならないことに注意してください。ブレークポイントを設定し、アドオンの機能を呼び出すと、動作するはずです。

API機能の呼び出し

ここからは、プランの壁の数をカウントする例のアドオンを書いてみましょう。
まず最初に、新しいヘッダーファイルをインクルードする必要があります。


#include "DG.h"
#include "DGModule.hpp"
#include "StringConversion.hpp"

// メニューコマンドを登録して、以下の例のように処理することができます。
// ユーザーがコマンドをクリックすると、コードはCountNumberOfWalls関数を呼び出します。

static GSErrCode MenuCommandHandler (const API_MenuParams *menuParams)
{
    switch (menuParams->menuItemRef.menuResID) { 。
        case ID_MENU_STRINGS:
            switch (menuParams->menuItemRef.itemIndex) {
                case 1:
                    CountNumberOfWalls ();
                    break;
            }
            break;
    }
    return NoError;
}

CountNumberOfWalls関数は、以下の例のように実装できます。


static void CountNumberOfWalls ()
{
    GS::Array<API_Guid> wallGuids;
    GSErrCode err = ACAPI_Element_GetElemList (API_WallID, &wallGuids);
    if (err != NoError) {
        return;
    }
 
    USize wallCount = wallGuids.GetSize ();
    DG::InformationAlert (GS::ValueToUniString (wallCount), "", "OK");
}

現在のプランから壁のリストにアクセスし、配列の長さをダイアログで表示しています。
問題がなければ、以下のように表示されるはずです。

アドオンのリリース

あなたのアドオンをリリースし、すべてのArchicadバージョンで動作させるには、Archicad開発者として登録し、あなたのアドオンのMDIDを取得する必要があります。MDIDはアドオンを識別するためのユニークな識別子です。Archicad は同じ MDID を持つ 2 つの異なるアドオンを読み込むことはできませんので、アドオンごとに異なるMDIDを設定する必要があることに注意してください。

MDIDの登録に関する詳細な説明はこちらをご覧ください。

リソース

ここでは基本的なことしか説明していませんが、他にもたくさんありますのでご覧ください。

  • より詳細な情報はArchicad API Referenceを参照してください。
  • もし困ったことがあれば、私たちのDeveloper Forumで質問することができます。
  • その他のチュートリアルについてはDeveloper Blogをご覧ください。
  • 最新のニュースを得るためにTwitterで私たちをフォローしてください。