アドオン開発の始め方

ここでは、ゼロからAdd-onを作成する方法を紹介します。

Archicadアドオンの基本

Archicadアドオンのプログラミング言語はC/C++ なので、この言語に慣れていないと始められません。またArchicad自体の機能やコマンドを知っていることが開発をする上でとても重要となります。

Archicadは様々な方法で拡張することができます：

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

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

必要なもの

Add-On開発をするには、以下の項目のセットアップが必要となります：

• GRAPHISOFT IDの作成および開発者登録
• Archicad
• API Development Kit
• CMake - IDEプロジェクトを生成するために必要です（バージョン3.16以上が必要）
• Python - ビルドツール用（バージョン2.7+または3.8+）
• 統合開発環境：Windows では Microsoft Visual Studio、MacOS では Xcode が必要になります。

Archicadバージョンに応じた開発環境を使用する必要がありますので、詳細は以下の表をご覧ください。

	Windows	MacOS
Archicad 24	Visual Studio 2017 (v141 ツールセット)	最新のXcode (deployment target　macOS 10.13)
Archicad 25	Visual Studio 2019 (v142 ツールセット)	最新の Xcode (deployment target macOS 10.15)
Archicad 26	Visual Studio 2019 (v142 ツールセット)	最新の Xcode (deployment target macOS 10.15)
Archicad 27	Visual Studio 2019 (v142 ツールセット)	最新の Xcode (deployment target macOS 10.15)
Archicad 28	Visual Studio 2019 (v142 ツールセット)	最新の Xcode (deployment target macOS 11.0)

API Kitの構成

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

• Documentation: APIのドキュメント用のフォルダです。ここには、すべてのAPI機能のリファレンスが記載されています。オンラインでも利用可能です。 　
• Examples: ここには、たくさんのアドオンの例があります。APIがどのように動作するかを理解するための良い出発点となります。プロジェクトをビルドして、その可能性を試して見てください
• Support:アドオン開発のためのすべてのヘッダーとライブラリファイル、およびリソースのコンパイル用ツールが含まれています。アドオンをビルドする際に必要となるフォルダです。

テンプレートからプロジェクトを作成しよう

サンプルのアドオンから始めることもできますが、GitHubにあるテンプレートから始める方が簡単です。

Archicad アドオンのテンプレートのダウンロードおよび使い方は以下のページにあります：

• Archicad Add-On CMake

IDEプロジェクトの生成

テンプレートをダウンロードしたら、プロジェクトの生成はQuick Setupの方法か、あるいはCMakeを使用して生成する方法もあります。CMakeを使用する場合、ルートフォルダから始めて、以下のコマンドでプロジェクトを生成できます。 変数AC_API_DEVKIT_DIRの値をDevKitのインストールフォルダに置き換えてください。

Windows:

mkdir Build
cd Build
cmake -G "Visual Studio 16 2019" -A "x64" -DAC\_API\_DEVKIT\_DIR="C:\\API Development Kit 28.3000" ..
cd ..

MacOS:

mkdir Build
cd Build
cmake -G "Xcode" -DAC\_API\_DEVKIT\_DIR=/Applications/GRAPHISOFT\\ ARCHICAD\\ API\\ DevKit\\ 28.3000 ..
cd ..

コマンドの最後にある「...」に注意してください。 これはCMakeが親フォルダ内のCMakeLists.txtファイルを検索することを意味します。

アドオンのビルド

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

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

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

• Windows: ARCHICAD.exe -DEMO
• MacOS: "ARCHICAD 2x.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 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 RegisterInterface (void)
{
    return ACAPI_Register_Menu (ID_ADDON_MENU, 0, MenuCode_Tools, MenuFlag_Default);
}
 
GSErrCode Initialize (void)
{
    return ACAPI_Install_MenuHandler (ID_ADDON_MENU, MenuCommandHandler);
}
 
GSErrCode FreeData (void)
{
    return NoError;
}

アドオンのリソース

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

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

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

リソースの日本語対応

テンプレートから作成したプロジェクトやサンプルプロジェクトでは、リソースに日本語を使用できません。日本語に対応するためには、リソースファイルをコンパイルするファイル（CompileResources.py）を修正します。

修正箇所

def RunResConvで使用するパラメータを変更

• '-c', '0'を追加
• codepageをutf-8に変更

# 修正後
result = subprocess.call ([
    self.resConvPath,
    '-m', 'r',                      # resource compile mode
    '-T', platformSign,             # target platform
    '-c', '0',                      # code page conversion for JPN
    '-q', 'utf8', 'utf8',           # code page conversion
    '-w', '2',                      # HiDPI image size list
    '-p', imageResourcesFolder,     # image search path
    '-i', inputFilePath,            # input path
    '-o', nativeResourceFilePath    # output path
])

def PrecompileResourceFileで使用するパラメータを変更

• execution-charset:を削除

# 修正後
result = subprocess.call ([
    'cl',
    '/nologo',
    '/X',
    '/EP',
    '/P',
    '/I', os.path.join (self.devKitPath, 'Inc'),
    '/I', os.path.join (self.devKitPath, 'Modules', 'DGLib'),
    '/I', self.sourcesPath,
    '/I', self.resourceObjectsPath,
    '/DWINDOWS',
    '/utf-8',
    '/Fi{}'.format (precompiledGrcFilePath),
    grcFilePath,
])

def CompileNativeResourceで使用するパラメータを変更

• '/c', '65001'を追加

# 修正後
result = subprocess.call ([
    'rc',
    '/c', '65001', # code page conversion for JPN
    '/i', os.path.join (self.devKitPath, 'Inc'),
    '/i', os.path.join (self.devKitPath, 'Modules', 'DGLib'),
    '/i', self.sourcesPath,
    '/i', self.resourceObjectsPath,
    '/fo', resultResourcePath,
    nativeResourceFile
])

コード

修正したファイルはこちらからダウンロードできます

デバッグ

デバッグはとても簡単で次の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で私たちをフォローしてください。