define material "pictmat" 0,
        1, 1, 1,             ! RGB
        0.5, 0.8, 0, 0,
        0, 0,
        0, 0, 0,
        0, 0, 0,
        0

material "pictmat"

picture "filename", a, b, mask

subtractionResult = subgroup ("sub_operand_1", "sub_operand_2")

Table 12.8. Infield with picture

A user interface picture used by only one object should be integrated in the library part file itself. This can be done using the LP_XMLConverter tool.

When using an external image referred to by its file name, don’t omit the file extension. This way, you will avoid errors stemming from pictures and objects having the same name.

Keep all pictures used by interface scripts in the Macros folder, or embedded in the object itself. Using external images: add the file_dependence command to make sure they are saved in archive format with the object.

Tab page handling

Starting from Archicad 18, a new hierarchical paging option is available for tabpage selection. This is accessed via the UI_PAGE command, by adding some extra parameters, and setting the Hierarchical Pages parameter in the object itself. Doing so, a separate popup tabpage control will appear above the custom UI field. The order and hierarchy of the available pages can be defined by the ID of the pages. Root ID is always -1. The possibility to set up an “oldschool” tabpage selector within the UI page still remains available.

Let’s see an example script:

! Master Script

! TabIDs
TABID_ROOT      = -1
TABID_PAGE_1    = 50
TABID_PAGE_2    = 60

dim uiUsedPageIDs[][2]
dim uiUsedPageNames[][2]
idxPage = 1

uiUsedPageNames[idxPage][1] = "PageName_1"
uiUsedPageNames[idxPage][2] = "pageIconName_1.png"

uiUsedPageIDs[idxPage][1]   = TABID_PAGE_1
uiUsedPageIDs[idxPage][2]   = TABID_ROOT    ! Parent Page ID

idxPage = idxPage + 1

uiUsedPageNames[idxPage][1] = "PageName_2"
uiUsedPageNames[idxPage][2] = "pageIconName_2.png"

uiUsedPageIDs[idxPage][1]   = TABID_PAGE_2
uiUsedPageIDs[idxPage][2]   = TABID_PAGE_1  ! Parent Page ID

file_dependence "pageIconName_1.png"
file_dependence "pageIconName_2.png"
file_dependence "pageIconName_3.png"

! Parameter Script

dim pageValues[]
for i = 1 to vardim1(uiUsedPageIDs)
    pageValues[i]= uiUsedPageIDs[i][1]
next i

values "gs_ui_current_page" pageValues

! UI Script

ui_dialog "Custom Settings Title"
ui_current_page gs_ui_current_page

for i = 1 to vardim1(uiUsedPageIDs)
    if uiUsedPageIDs[i][1] = TABID_PAGE_1 then
        ui_page uiUsedPageIDs[i][1],    uiUsedPageIDs[i][2],
                uiUsedPageNames[i][1],  uiUsedPageNames[i][2]
        if gs_ui_current_page = TABID_PAGE_1 then
            gosub "pageSubroutinTitle_1"
        endif
    endif

    if uiUsedPageIDs[i][1] = TABID_PAGE_2 then
        ui_page uiUsedPageIDs[i][1],    uiUsedPageIDs[i][2],
                uiUsedPageNames[i][1],  uiUsedPageNames[i][2]
        if gs_ui_current_page = TABID_PAGE_2 then
            gosub "pageSubroutinTitle_2"
        endif
    endif
next i

! ==============================================================================
! Call User Interface Macro's TabPages
! ==============================================================================

call "ui_customMacro" parameters all    uiUsedPageIDs   = uiUsedPageIDs,
                                        uiUsedPageNames = uiUsedPageNames

! ==============================================================================
end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! en
! ==============================================================================

! ==============================================================================
! UI Page Subroutines
! ==============================================================================

"pageSubroutinTitle_1":
    ! UI Page 1 description
return


"pageSubroutinTitle_2":
    ! UI Page 2 description
return

Thumbnail controls with dynamic items

From Archicad 10 on, a new dynamic method is available for linking control items and value list items. Using this method you can localize the logic of the availability of parameter values to the parameter script – the control will adopt the set of available values. This dynamic linking is available for ui_infield{3} and ui_infield{4}. The old-style static linking is still working for static functions (using ui_infield and ui_infield{2}).

The two components of the dynamic method are:

1. Define the user interface control with an option for every possible value.

The example shows a popup menu control (method = 2) which uses an index image containing 2 rows and 4 columns. The sample control supports 8 possible values.

ui_infield{3} iJunctionType, xColumn1-10, 44, 200, 50,
    2, 3, 8, 2,
    70, 45, 70, 45,
    1, `Junction Type A1`, 2,
    2, `Junction Type B1`, 4,
    3, `Junction Type C1`, 1,
    4, `Junction Type D1`, 3,
    5, `Junction Type A2`, 5,
    6, `Junction Type B2`, 7,
    7, `Junction Type C2`, 6,
    8, `Junction Type D2`, 8

2. Set the list of available values for the parameter under the given circumstances.

if iLeftNeighbour = 1 then
    values "iJunctionType" 1, 3, 4, 6
else
    if iRightNeighbour = 1 then
        values "iJunctionType" 2, 5, 7, 8
    else
        values "iJunctionType" 1, 5, 7
    endif
endif

The resulting control is shown in the image below. (iLeftNeighbour = 0, iRightNeighbour = 1)

Transparent UI pictures

In Archicad 10 a new method has been introduced that can handle alpha-layer based transparent pictures. The following controls handle pictures with alpha layers correctly:

• ui_pict
• ui_infield{3}, method = 1 (thumbnail view control)
• ui_infield{3}, method = 2 (popup with icons and texts)
• ui_infield{3}, method = 3 (popup with icons only)
• ui_infield{3}, method = 4 (icon radio push button)
• ui_infield{4}, method = 1 (thumbnail view control)
• ui_infield{4}, method = 2 (popup with icons and texts)
• ui_infield{4}, method = 3 (popup with icons only)
• ui_infield{4}, method = 4 (icon radio push button)

Font sizes on the UI

If you use static texts (possibly in combination with the ui_style command), be aware of the following.

Because of the differences of the targeted operating systems, font sizes are not the same on Windows and on Mac. As a side effect, the extra small font size is a bit larger than the small one on Windows. As a general rule, always test user interfaces on both platforms to check overlapping and clipping.

Furthermore, special styles like Bold, Italic and Underline are not allowed in combination with extra small size. Outline and Shadow are old Macintosh styles, which are no longer used.

The two pictures show the look of static texts with different sizes and styles.

On Windows:

On Mac:

Forward Migration script

Execution context

The FWM script is executed when a project saved in an earlier version of Archicad is opened in a later version (starting with Archicad 15) with the updated library. This new library can be loaded manually or by using the Consolidate option in the Library Manager. If a placed instance of an object has a new, changed Main ID and a valid Forward Migration Script in the new library, it can be automatically substituted by Archicad. If the execution of the script is successful, the old element gets replaced by the new one. This script enables the object to set the new parameters based on the old ones, without feature loss or a major change in appearance.

General recommendation

The first line of the script fills the FROM_GUID global variable (this contains the main ID of the original object to be migrated) into the “actualGuid” variable. You may want to use the following structure to ensure maintainability.

The rest of the script is divided into subroutine calls, one for every change of GUID. Every block must have a corresponding line in the Migration Table of the object and a block in the Backward Migration script. The latest change of Main ID always has to be the last call of this script. In every block you set the ID to start from (_startID), and the one to end up with (_endID), define the migration logic in a subroutine (for details and GDL commands, see the GDL Reference Guide), and at the end of the block you always set the new “_endID” (or set an empty ID, which means that the upgrade process will stop at the previous block’s version of the object) into the “actualGuid” variable. Example:

actualGUID = FROM_GUID

! ==============================================================================
! Subroutines
! ==============================================================================

    _startID    = "AAAA-AAAA-...AAA"
    _endID      = "BBBB-BBBB-...BBB"
gosub "migrationstepname_FWM"

! ==============================================================================
! Set Migration GUID
! ==============================================================================

setmigrationguid actualGUID

! ==============================================================================
end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! en
! ==============================================================================


! ==============================================================================
! migrationstepname
! ==============================================================================
"migrationstepname_FWM":
    if actualGuid = _startID then
        newParameter = oldParameter
        parameters newParameter = newParameter
        actualGuid = _endID
    endif
return

Backward Migration script

Execution context

The BWM script is executed when a project is saved to the previous version of Archicad.
If the current version of the library part has a different Main ID than its equivalent in the previous version, the migration script of the object is evaluated. As a result, the libpart will be either downgraded if possible (sometimes with some minor compromise, if it does not affect the item’s main functions), or will be lost completely (in this case, it will appear as a “missing” dot sign in the earlier version project). The latter happens when a new function set introduced in the current version represents a major change compared to the previous version.

A successful backward migration process should convert the object’s parameters in a way that avoids major feature loss or changes in appearance.

General recommendation

The first line of the script sets the continuity control variable to valid. You may want to use the following structure to ensure maintainability.

The rest of the script is divided into subroutines: one change of Main ID is one subroutine. Every subroutine must have a corresponding line in the Migration Table of the object and a corresponding subroutine in the Forward Migration script. The latest step back in changing Main ID always has to be the first subroutine of this script.

At the start of each subroutine the target GUID is checked. If not empty, the script runs in called order. Backward migration only works for one version back, so the targetGUID only needs to be set once (except when you make a fork in the migration to separate previous-version objects).

The end of the subroutine is about setting the destination (old) ID into the “targetGuid” variable. If you set an empty ID to the variable, the downgrade process is canceled there. If the “targetGuid” matches the TO_GUID global variable (containing the main ID of the target element in the conversion), the first part of the migration process is complete.

Adding a title or a short description of the migration step for every subroutine is highly recommended. You should use the same title for the Forward Migration script pair of the subroutine.

After you have reached the desired stage of the object’s devolution, you have to set the placed object’s ID by using the setmigrationguid command.

In case the migration returns an empty ID, the element is going to be missing from the project opened in the previous version.

targetGUID = TO_GUID

! ==============================================================================
! Subroutines
! ==============================================================================

gosub "migrationstepname_BWM"

! ==============================================================================
! Set Migration GUID
! ==============================================================================

setmigrationguid targetGUID

! ==============================================================================
end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! en
! ==============================================================================


! ==============================================================================
! migrationstepname
! ==============================================================================
"migrationstepname _BWM":
    if targetGUID # "" then
        bMigrationSuccess = 1
        if bMigrationSuccess = 1 then
            oldParameter = newParameter
            parameters oldParameter = oldParameter
        else
            targetGuid = ""
        endif
    endif
return

Migration table

Every time you change an object’s Main ID, you need to fill in the old ID into the Migration Table of the element. Each line contains a previous ID and an Archicad version number (or 0, if you change more than once between two versions). During forward migration, the program scans this list of ID-s, preselecting the elements available for the migration process. During backward migration, scanning this list the program chooses only those with a version equivalent to the previous Archicad version. Every line of this table must have at least one corresponding subroutine in the Forward Migration script and the Backward Migration script. Automigration can be used to run the parameter script without having to write a migration script that would only unconditionally change the GUID. It is useful if the migration code would have to be copied in the parameter script too for non-migrated elements (e.g. synchronizing parameters is needed as a bugfix or because new ac_ parameters).