FAQ

Frequently asked questions

1. What's the required format of User Controls in the .grc file?

The required format of UserControl items in the .grc files always caused a headache. In this document, we'll explain the meaning of the different numbers behind the UserControl definition. Let's see them type by type. The examples were mostly taken from DG_Test, which is part of the development kit.

UserControl 257

This control is a collection of special controls; it encapsulates controls which are very different in appearance, but not in functionality. Basically this control consists of a button, which pops up a palette when clicked. The content of the button is updated as the user moves the mouse above the palette.

Examples: material, pen, layer palette pop-up.

The generic format of this control is:

UserControl   87 82 33 19 257   0x0001   0x1100   0   /* Line Pen Setting */

Let's see the 'numbers' one by one:

Item	Description	Example
UserControl	the type of the dialog item
87 82 33 19	the item's rectangle (top, left, width, height)
257	the type of the user control
0x0001	defines the subtype of the user control (see the constants starting with T257_ in UCDefs.h) Note: 0x0001 is T257_PEN, so this is a pen control
0x1100	the upper byte modifies the appearance of the user control (see the constants starting with CS257_ in UCDefs.h) Note: not all the flags are valid for all types of controls the lower byte is always 00	0x11 is CS257_HEADER | CS257_SMALLFONT, so the pop-up palette will have a header, and the menu items and the header will use the small application font.
0	used in textual pop-ups only T257_TEXT and T257_MENU; it contains the id of the ‘'STR#’` resource containing the menu items Note: due to a bug in the dialog manager, this cannot be used at the moment

UserControl 258

This control is an icon-based pop-up control. The icons coming from the specified resource appear on the pop-up palette.

Example: suspend groups selector on the control box.

The generic format of this control is:

UserControl   12  8  66 22  258  2  14  0  1  32520

Let's see the 'numbers' one by one:

Item	Description
UserControl	the type of the dialog item
12 8 66 22	the item's rectangle (top, left, width, height)
258	the type of the user control
2	specifies the number of rows you would like to see the icons
14	tells the total number of icons
0	always
1	modifies the appearance of the user control (combination of the constants starting with CS258_ in UCDefs.h)
1	is CS258_HEADER ⇒ the pop-up palette will have a header
2	is CS258_MOUSEPOSOPEN ⇒ the pop-up palette will appear relative to the mouse position, (as opposed to the control's rectangle)
4	is CS258_SIMPLEFRAME ⇒ the pop-up palette will have a simpler frame (Windows only)
32510	id of the icon resource; contains all the icons. This icon is cut into pieces to create the individual icons. This also servers as the resource ID of the title strings, if the popup palette has a header (CS258_HEADER).

UserControl 259

This control is an icon-based control. The icons coming from the specified resource are layed out flat.

Example: type selector in the library browser.

The generic format of this control is:

UserControl   12  8  30  28  259  1  3  0  0  32510

Let's see the 'numbers' one by one:

Item	Description
UserControl	the type of the dialog item
12 8 30 28	the item's rectangle (top, left, width, height)
259	the type of the user control
1	specifies the number of rows you would like to see the icons
3	tells the total number of icons
0	always
0	always
32510	id of the icon resource; contains all the icons

UserControl 261

This control is the line type pop-up control. The content of the button is updated as the user moves the mouse above the palette. The specialty of this control is that it calls back to the server application to draw the line type into the control.

Example: any line type pop-up.

The generic format of this control is:

UserControl   42  0  260  40  261  0x0100   /* Line type for Line Tool */

Let's see the 'numbers' one by one:

Item	Description	Example
UserControl	the type of the dialog item
42 0 260 40	the item's rectangle (top, left, width, height)
261	the type of the user control
0x0100	the upper byte modifies the appearance of the user control (see the constants starting with CS261_ in UCDefs.h) the lower byte is always 00	0x01 is CS261_HEADER, so the pop-up palette will have a header.

1. I receive this error message: "This add-on cannot be validated. Please contact the distributor." What is the problem?

   Several problems may lead to this message:

   • The add-on cannot be loaded, because the dll / shared library cannot be loaded. This usually indicates a missing library, or some initialization failure. The first problem can be detected by the Depends.exe application on Windows (it's part of the MS tool suite). On Mactel, the 'otool -L' Terminal command lists the frameworks referred by the add-on. The second problem is usually in the add-on's code :))
   • The add-on was not compiled with the DevKit required by the server application.
   • The add-on doesn't have an 'MDID' resource, or the 'MDID' resource doesn't contain valid information. This may be caused by:
     • Mac: the add-on doesn't have a resource fork, because of an invalid transfer through internet or file system.
     • the MDID resource was not compiled into the add-on.
     • the MDID resource contains demo IDs (e.g. developer ID is 1 and the local ID is 1)
     • the MDID clashes with another add-on's MDID; in this case Archicad refuses to load any of these add-ons.
     • there's a typo in the developer ID, or in the authorization code. In this case the generated local ID looks valid, but Archicad still rejects to load the add-on. Try to double-check the ID and the code with Graphisoft.
2. How do I create a template library part to be used in my add-on?
   1. Create a new library part in Archicad, and insert it into the correct place in the subtype hierarchy with the Select Subtype button: (in this example I shall insert the object as the subtype of Model Element). Also check the 'Use as subtype' checkbox.
      
      Then save this object as, let's say "Zoom GDL Object". You can check whether this has been inserted into the object hierarchy correctly if you bring up the File / GDL Object / Open Object by Subtype... dialog.
      
   2. Add this 'Zoom GDL Object' to your Add-On in a FILE resource: The name of the resource ("Zoom Object.gsm") will appear in the Object Settings dialog, and the content of the resource refers to name of the file ("Zoom GDL Object.gsm") you would like to include in your add-on. 'FILE' 132 "Zoom Object.gsm" { "Zoom GDL Object.gsm" }
   3. Call ACAPI_AddOnIntegration_RegisterBuiltInLibrary from your RegisterInterface () function.
   4. If you want to create a new object whose parent is this object in the subtype hierarchy, then before calling ACAPI_LibraryPart_Create fill in the parentUnID field of the API_LibPart structure this way: ACAPI_LibraryPart_GetBuiltInLibpartUnId (132, libPart.parentUnID); // 132 is the 'FILE' resource ID
   5. Set the placeable, and clear the template field of the API_LibPart structure.
   6. After this you can call ACAPI_LibraryPart_Create, and the library part will be inserted into the correct place in the subtype hierarchy.

3. How do I create an associative dimension in Archicad?

   An example from the Automatic Dimensioning add-on shows how you can convert the old neig IDs to the new bool fields in API_Base :

   bool    NeigID2Line (API_NeigID neigID)
   {
       return (neigID == APINeig_WallOn        ||
               neigID == APINeig_WallPlOn      ||
               neigID == APINeig_WallPlOnClOff ||
               neigID == APINeig_BeamOn        ||
               neigID == APINeig_CeilOn        ||
               neigID == APINeig_RoofOn        ||
               neigID == APINeig_MeshOn        ||
               neigID == APINeig_HatchOn       ||
               neigID == APINeig_LineOn        ||
               neigID == APINeig_ArcOn         ||
               neigID == APINeig_SplineOn      ||
               neigID == APINeig_CurtainWallOn ||
               neigID == APINeig_CurtainWallCutOn);
   }
    
   bool    NeigID2Special (API_NeigID neigID)
   {
       return (neigID == APINeig_WallPl    || neigID == APINeig_WallPlOn ||
               neigID == APINeig_WallPlClOff || neigID == APINeig_WallPlOnClOff ||
               neigID == APINeig_BeamHole  ||
               neigID == APINeig_WindHole  ||
               neigID == APINeig_DoorHole  ||
               neigID == APINeig_MeshRidge || neigID == APINeig_MeshRidgeOn ||
               neigID == APINeig_CurtainWallCut  || neigID == APINeig_CurtainWallCutOn);
   }
    
   static void MakeDimelemForWD (API_DimElem* dimelem, const MyCoord& mc)
   {
       for (const WallRef& wr : mc.wrs) {
           if (wr.m_openingpt != NOOPENINGPT) {
               switch (wr.m_openingType.typeID) {
                   case API_WindowID:
                   case API_DoorID:
                       switch (wr.m_openingpt) {
                           case OPENINGWH0:
                           case OPENINGWH1:
                           case OPENINGN0:
                           case OPENINGN1:
                           case OPENINGU0:
                           case OPENINGU1:
                           case OPENINGR0:
                           case OPENINGR1:
                           case OPENINGE0:
                           case OPENINGE1:
                           case OPENINGL0:
                           case OPENINGL1:
                               dimelem->base.base = wr.m_base;
                               break;
                           default:
                               dimelem->base.base = wr.m_base;
                               break;
                       }
                       break;
                   case API_CurtainWallFrameID:
                       dimelem->base.base = wr.m_base;
                       break;
               }
               return;
           }
           else {
               if (wr.m_openingPtType == CORNERCORNER) {
                   dimelem->base.base.type    = API_WindowID;
                   dimelem->base.base.special = false;
                   dimelem->base.base.line    = false;
                   dimelem->base.base.inIndex = wr.m_inIndex;
                   dimelem->base.base.guid    = wr.m_guid;
                   return;
               }
           }
       }
    
       // Error if it comes here...
       return;
   }

4. _(Win only) My add-on runs perfectly on my development machine, but when I install it on a demo machine it refuses to load._

   This usually happens from one of the following reasons:

   • Visual Studio installs its own runtime libraries (MSVCxx.DLL and MSVCPxx.DLL) in the WINNT\System32 folder, and the APX is usually dynamically linked to those, i.e. it expects the DLLs to be there. On the systems you didn't install Visual Studio, the DLLs are simply not there. You can try to solve this by copying those files over to the appropriate place from the machines where you have Visual Studio installed. Note: Archicad installs the necessary runtime libraries if they are not there.
   • You are trying to install a debug version of your add-on onto the demo machine. This won't work, because it is linked to the debug libraries of Visual Studio, which are not present on the demo machine. Compile a release version instead.

5. Can I compile a GDL add-on, which uses the services of the General API DevKit?

   No. GDL add-ons use their own API environment, and that mixes quite badly with the General API running environment.

6. How can I catch notifications immediately?

   Return APIAddon_Preload from your CheckEnvironment () function. This will ensure that your Initialize () function will be called immediately after the call to Registerface (), without requiring the user to perform any action. You can then safely install the notification callback function(s) from Initialize ().

7. We defined an icon in the GRC file in the 3.1 DevKit, but they doesn't seem to appear with the newer devkits, and I also receive a resource conversion error. Also, what do those three numbers mean in the resource?

   'GICN' 32501 "General Settings" {
   0  128  128
   }
   

   The '0 128 128' is the R/G/B color (respectively) of the transparent area in the icon; each component is in the range 0-255. The reason why is doesn't compile with DevKit 6.1 is because some of the colors (black and white) should be in fixed places within the icon's color table: black should be the first color, and white should be the last. Note that the icons are converted to 32-bit depth, so you cannot use arbitrary big sizes.

8. I'm creating a library part from my add-on, and I also put in a preview picture, but it doesn't appear.

   From Archicad 8 you should add the MIME type of the preview picture as a C string (with the terminating 0) to the beginning of the data handle containing the preview picture. (e.g. "image/png\\0" for a PNG image)

9. Is there a default callback for the simple popup menu-like custom control?

   No. You'll have to write your own callback to load the data from your resource file, and pass it to the user control with UC257SetData. You'll also have to call UC257SetType, and possibly UC257SetStyle. The DG_Test example now shows how you can work with these functions.

10. _(Win only) When I link my add-on, I receive the following warning: LINK : warning LNK4098: defaultlib "MSVCRT" conflicts with use of other libs; use /NODEFAULTLIB:library_

    This only means that you are compiling the debug version of your add-on (thus linking to the debug version of the runtime DLLs), whereas the libraries shipped with the DevKit are release versions (which are linked to the release version of the runtime DLLs). This doesn't cause any problem.

11. How can I open a progress window when I have a long process running?

    In several ways:

    1. use the set of functions (ACAPI_ProcessWindow_InitProcessWindow, etc.) provided by the API. This has a small problem: other processes within Archicad are using the same progress window, and they can interfere with the information displayed by your add-on.
    2. use your own modeless palette as a process window.
    3. open a modal dialog, and drive the process from there. Since DevKit v4.1 you can switch databases even if a modal dialog is visible on the screen. See the Do_ProgressWindow function in the DG_Test example. This is the recommended solution at the moment.

12. I have a function which adjusts the additional parameter values of a placed object/window/door. It works fine in Archicad 7, but not in Archicad 8 or 9.

    This problem usually occurs when you refer to the additional parameters by indices:

    (*memo.params)[27].value.real = 7.25;

    The problem is coming from the subtype hierarchy: an object/window/door in the hierarchy inherits the parameters of all of its ancestors. So, you should refer to a parameter by name instead of its index. This also means you'll have to look up the parameter by name before modify its value:

    static void SetParValue (API_AddParType *** addPars, const char * name, const double &val)
    {
        if (addPars == nullptr || *addPars == nullptr)
            return;
     
        Int32 ii, addParNum = BMGetHandleSize (reinterpret_cast<GSHandle> (*addPars)) / sizeof (API_AddParType);
        for (ii = 0; ii < addParNum; ii++) {
            if (CHCompareCStrings ((**addPars)[ii].name, name, CS_CaseInsensitive) == 0) {
                (**addPars)[ii].value.real = val;
                break;
            }
        }
     
        return;
    }   // SetParValue

13. When I read 3D data for an element I don't get the correct 3D-vertex world-coordinates. They are local coordinates for that element. So how can I retrieve the correct vertex information in world coordinates of an element?

    Each 3D body contains a transformation matrix (see API_BodyType), which should be applied to the coordinates of the vertices. This allows us to store a body which has several instances very compactly (i.e. store the vertices just once, and have a different transformation matrix for every instance).

14. How can I make the standard DXF/DWG add-on export elements into DWG file?

    You can find a simple example at the description of the ACAPI_AddOnAddOnCommunication_Call function.