ObjectARX 开发完全指南 (从入门到精通)

第一章：ObjectARX 是什么？

在开始编码之前,我们首先要理解 ObjectARX 的本质。

1 什么是 ObjectARX？

ObjectARX (AutoCAD Runtime eXtension) 是 Autodesk 官方提供的 C++ 开发工具包，用于在 AutoCAD 平台上进行二次开发，通过 ObjectARX，你可以：

• 创建自定义命令：像 LINE, CIRCLE 一样，在命令行输入你的命令来执行特定功能。
• 访问和修改数据库：直接读写 AutoCAD 图形中的所有对象（实体、线型、图层、文字样式等）。
• 创建自定义实体：开发具有独特行为和绘制逻辑的全新图形对象。
• 事件监听：在特定事件（如打开/关闭文件、开始/结束命令、修改对象）发生时自动执行你的代码。
• 与 Windows UI 集成：创建自定义对话框、工具栏、菜单等。

ObjectARX 赋予了你“深度”定制 AutoCAD 的能力，使其成为一个完全符合你工作流程的强大工具。

2 ObjectARX、.NET API 和 LISP 的区别

对于追求极致性能和功能的开发者,ObjectARX 是不二之选，本教程将专注于 ObjectARX。

第二章：开发环境准备

工欲善其事,必先利其器，我们需要搭建好 C++ 开发环境。

1 必需软件

1. Visual Studio：推荐使用 Visual Studio 2025 或 Visual Studio 2025，社区版是免费的，完全足够使用。
2. AutoCAD：你需要一个 AutoCAD 版本（如 AutoCAD 2025）来开发和测试，不同版本的 AutoCAD 对应不同版本的 ObjectARX SDK。
3. ObjectARX SDK：这是开发的核心库文件，你需要从 Autodesk 官网下载与你 AutoCAD 版本匹配的 SDK，如果你用 AutoCAD 2025，就下载 ObjectARX 2025 SDK。
   • 下载地址：Autodesk 开发者中心

2 安装与配置

1. 安装 Visual Studio：在安装时，请务必勾选 “使用 C++ 的桌面开发” 工作负载。
2. 安装 AutoCAD：正常安装即可。
3. 安装 ObjectARX SDK：将下载的 SDK 压缩包解压到一个固定路径，C:\Autodesk\ObjectARX 2025。
4. 配置 Visual Studio 项目：
   • 打开 Visual Studio，创建一个新的 动态链接库 项目。
   • 项目属性配置：这是最关键的一步，右键点击项目 -> 属性。
     • 配置属性 -> VC++ 目录 -> 包含目录：添加 ObjectARX SDK 下的 inc 文件夹路径。
       • C:\Autodesk\ObjectARX 2025\inc
     • 配置属性 -> VC++ 目录 -> 库目录：添加 ObjectARX SDK 下的 lib 文件夹路径。
       • C:\Autodesk\ObjectARX 2025\lib
     • 配置属性 -> 链接器 -> 输入 -> 附加依赖项：添加对应的库文件。
       • 对于 64 位 AutoCAD，通常需要：AcDb.lib, AcCore.lib, AcGi.lib, AcRx.lib。

第三章：第一个 ObjectARX 程序 - "Hello, World!"

让我们从一个最简单的例子开始,创建一个在命令行打印 "Hello, ARX World!" 的命令。

1 代码结构

一个基本的 ObjectARX 应用程序通常包含以下几个部分：

1. 头文件：包含必要的 ARX 头文件。
2. 入口点：acrxEntryPoint 函数，这是 ARX 应用程序的入口。
3. 初始化和卸载函数：在加载和卸载时执行。
4. 命令定义：使用 ACED_REGIST_COMMAND 注册你的自定义命令。

2 完整代码 (HelloArx.cpp)

// 包含必要的 ARX 头文件
#include "StdAfx.h" // 必须是第一个，用于预编译头
#include "aced.h"   // AutoCAD 命定义和入口点
#include "dbents.h" // 数据库实体
#include "tchar.h"  // 支持 Unicode
// 声明一个函数，这个函数将作为我们的自定义命令
void helloWorld(void);
// acrxEntryPoint 函数是所有 ARX 应用程序的入口点
// 它处理应用程序的加载、卸载和命令调用
extern "C" AcRx::AppRetCode acrxEntryPoint(AcRx::AppMsgCode msg, void* pkt)
{
    switch (msg)
    {
    case AcRx::kInitAppMsg:
        // 应用程序被加载时执行
        acrxDynamicLinker->unlockApp(pkt);
        acrxRegisterApp(pkt);
        // 注册我们的自定义命令
        // "HELLO" 是命令名，"helloWorld" 是命令对应的函数
        acedRegCmds->addCommand("MY_COMMANDS", "HELLO", "HELLO", ACRX_CMD_TRANSPARENT, helloWorld);
        break;
    case AcRx::kUnloadAppMsg:
        // 应用程序被卸载时执行
        acrxRemoveApp(pkt);
        break;
    }
    return AcRx::kRetOK;
}
// 自定义命令的实现
void helloWorld(void)
{
    //acedPrompt("\nHello, ARX World!\n"); // 在命令行提示信息
    acedAlert(_T("Hello, ARX World!")); // 弹出一个警告框
}

3 代码解释

• #include "StdAfx.h"：非常重要，这是 Visual Studio 的预编译头文件，必须放在所有其他头文件之前。
• aced.h：包含了定义命令和与 AutoCAD 交互的核心函数。
• acrxEntryPoint：这是 ARX 应用程序的“心脏”。
  • kInitAppMsg：当你在 AutoCAD 中使用 NETLOAD 或 APPLOAD 加载这个 .dll 文件时，会收到这个消息，我们注册应用程序和我们的命令 HELLO。
  • kUnloadAppMsg：当卸载 .dll 文件时，会收到这个消息，我们注销应用程序。
• acedRegCmds->addCommand(...)：这是注册命令的关键函数。
  • "MY_COMMANDS"：一个命令组名，用于组织命令。
  • "HELLO"：要注册的命令名称（不区分大小写）。
  • "HELLO"：命令的本地名称（用于多语言）。
  • ACRX_CMD_TRANSPARENT：命令标志，ACRX_CMD_TRANSPARENT 表示命令是“透明的”，可以在其他命令执行过程中嵌套使用，对于简单命令，可以设为 0。
  • helloWorld：当用户输入 HELLO 命令时，要调用的 C++ 函数指针。
• helloWorld 函数：
  • acedPrompt：在命令行向用户显示提示信息。
  • acedAlert：弹出一个简单的 Windows 消息框。_T() 宏用于支持 Unicode 字符串。

4 编译与加载

1. 编译：在 Visual Studio 中，确保配置为 Release 和 x64（如果你的 AutoCAD 是 64 位的），然后生成解决方案，你会在项目的输出目录（如 x64\Release）下得到一个 .dll 文件。
2. 加载：
   • 打开 AutoCAD。
   • 在命令行输入 NETLOAD (或 APPLOAD，但 NETLOAD 更现代)。
   • 找到你刚刚编译生成的 .dll 文件并打开。
   • 加载成功后,在命令行输入 HELLO，你应该会看到一个弹窗或在命令行看到 "Hello, ARX World!"。

第四章：核心概念深入

1 AutoCAD 数据库

AutoCAD 图形文件（.dwg）本质上是一个数据库，ObjectARX 开发的大部分工作就是与这个数据库交互。

• 数据库：AcDbDatabase 对象代表整个 DWG 文件。
• 对象：数据库中的任何一项都是一个对象，如 AcDbLine（直线）、AcDbCircle（圆）、AcDbLayerTableRecord（图层）等，它们都继承自基类 AcDbObject。
• 符号表：用于存储特定类型的对象，是数据库的“索引”。
  • 层表：存储所有图层。
  • 线型表：存储所有线型。
  • 文字样式表：存储所有文字样式。
  • 块表：存储所有块定义。
• 对象 ID：每个数据库对象都有一个唯一的 AcDbObjectId，通过它可以找到并操作这个对象。

2 事务

在修改数据库时,必须使用事务来保证操作的原子性，一个事务要么全部成功，要么全部失败回滚，不会出现图形被部分修改的“损坏”状态。

基本模式：

AcDbDatabase* pDb = acdbHostApplicationServices()->workingDatabase();
AcDbTransaction* pTrans = acdbTransactionManager->startTransaction();
if (pTrans == NULL) {
    // 处理错误
    return;
}
AcDbObject* pObject = ...;
// 在事务中打开和修改对象
AcDbEntity* pEntity = AcDbEntity::cast(pObject);
if (pEntity) {
    pEntity->setColorIndex(1); // 修改颜色
    pEntity->upgradeOpen();   // 如果对象是只读的，需要先“升级”打开
    pEntity->downgradeOpen(); // 修改完成后，可以“降级”打开以提高性能
    eOk = pEntity->close();
}
// 提交事务，使修改永久生效
pTrans->commit();
// 结束事务
pTrans->close();

第五章：实战案例 - 创建和修改直线

让我们结合前面所学,完成一个更实际的例子：在模型空间创建一条红色的直线，然后将其颜色改为蓝色。

1 创建直线

void createLine()
{
    // 1. 获取当前数据库
    AcDbDatabase* pDb = acdbHostApplicationServices()->workingDatabase();
    // 2. 开始一个事务
    AcDbTransaction* pTrans = acdbTransactionManager->startTransaction();
    if (!pTrans) {
        acedAlert(_T("Failed to start transaction."));
        return;
    }
    // 3. 获取块表和模型空间记录
    AcDbBlockTable* pBlockTable;
    Acad::ErrorStatus es = pTrans->getObject(pDb->blockTableId(), AcDb::kForRead, pBlockTable);
    if (es != Acad::eOk) {
        pTrans->abort();
        pTrans->close();
        return;
    }
    AcDbBlockTableRecord* pModelSpace;
    es = pTrans->getObject(pBlockTable->modelSpaceId(), AcDb::kForWrite, pModelSpace);
    pBlockTable->close();
    if (es != Acad::eOk) {
        pTrans->abort();
        pTrans->close();
        return;
    }
    // 4. 创建一条新的直线对象
    AcDbLine* pLine = new AcDbLine(AcGePoint3d(0, 0, 0), AcGePoint3d(100, 100, 0));
    // 5. 设置直线属性（颜色）
    pLine->setColorIndex(1); // 1 = 红色
    // 6. 将直线添加到模型空间
    es = pModelSpace->appendAcDbEntity(pLine);
    pModelSpace->close();
    if (es != Acad::eOk) {
        delete pLine; // 如果添加失败，删除对象
        pTrans->abort();
    } else {
        // 7. 提交事务
        pTrans->commit();
        delete pLine; // 释放对象所有权，数据库现在管理它
    }
    // 8. 关闭事务
    pTrans->close();
}

2 修改直线

假设我们要将所有颜色为红色的直线（颜色索引 1）改为蓝色（颜色索引 5）。

void changeRedLinesToBlue()
{
    AcDbDatabase* pDb = acdbHostApplicationServices()->workingDatabase();
    AcDbTransaction* pTrans = acdbTransactionManager->startTransaction();
    if (!pTrans) return;
    // 1. 获取块表和模型空间
    AcDbBlockTable* pBlockTable;
    pTrans->getObject(pDb->blockTableId(), AcDb::kForRead, pBlockTable);
    AcDbBlockTableRecord* pModelSpace;
    pTrans->getObject(pBlockTable->modelSpaceId(), AcDb::kForWrite, pModelSpace);
    pBlockTable->close();
    // 2. 遍历模型空间中的所有实体
    AcDbObjectIterator* pIter = pModelSpace->newIterator();
    for (; !pIter->done(); pIter->next()) {
        AcDbEntity* pEntity = AcDbEntity::cast(pIter->entity());
        if (!pEntity) continue;
        // 3. 检查实体颜色
        Adesk::UInt16 color;
        pEntity->getColor(color, NULL); // 获取颜色索引
        if (color == 1) { // 如果是红色
            pEntity->upgradeOpen(); // 从只读升级为可写
            pEntity->setColorIndex(5); // 改为蓝色
            pEntity->downgradeOpen(); // 降级为只读
        }
        pEntity->close();
    }
    delete pIter;
    // 4. 提交并关闭
    pModelSpace->close();
    pTrans->commit();
    pTrans->close();
}

第六章：进阶主题

当你掌握了基础后,可以探索更高级的功能：

• 自定义实体：继承 AcDbEntity 类，创建具有自定义绘制逻辑、数据存储和用户交互的复杂图形对象。
• 反应器：创建一个“监听器”，在特定事件（如数据库修改、命令开始等）发生时自动执行代码，创建一个监听器，当用户删除一个图层时，自动删除该图层上的所有对象。
• MFC/Windows UI 集成：使用 MFC (Microsoft Foundation Classes) 创建复杂的对话框、工具栏和菜单，并与 ARX 逻辑结合。
• 多文档界面 支持：让你的应用程序能够同时处理多个打开的 AutoCAD 图形窗口。

第七章：学习资源与调试

1 官方资源

• Autodesk 开发者中心：https://www.autodesk.com/developer-network

  这是获取最新 SDK、文档和示例代码的最佳来源。

• ObjectARX SDK 文档：SDK 中包含详细的 .chm 帮助文件，是查阅函数和类的“圣经”。
• 官方示例：SDK 的 Samples 文件夹中包含了大量示例代码，是学习最佳实践的宝贵资料。

2 调试技巧

调试 ARX 应用程序比调试普通程序复杂，因为它运行在 AutoCAD 进程中。

1. 附加到进程：
   • 在 Visual Studio 中，选择 调试 -> 附加到进程。
   • 在进程列表中找到 acad.exe (AutoCAD 进程)。
   • 勾选 “显示所有用户的进程” 如果需要。
   • 点击 “附加”。
2. 设置断点：在你想要调试的代码行（如 helloWorld 函数内部）设置断点。
3. 加载和触发：在 AutoCAD 中加载你的 ARX 程序，然后输入你的命令（如 HELLO），程序执行到断点处会暂停，你就可以像调试普通程序一样查看变量、调用堆栈等。

ObjectARX 开发是一条强大但陡峭的学习之路，本教程为你提供了一个清晰的路线图：

1. 理解概念：明白 ARX 是什么，以及它与其他技术的区别。
2. 搭建环境：正确配置 VS 和 ARX SDK。
3. 入门实践：从 "Hello, World!" 开始，编译、加载、运行。
4. 掌握核心：深入理解数据库、事务、对象 ID 等核心概念。
5. 实战演练：通过创建和修改实体来巩固知识。
6. 持续探索：挑战自定义实体、反应器等高级主题。

最重要的是,多看官方文档，多研究示例代码，多动手实践，祝你开发顺利！