Part 4: UI Controls

FlashUIControl(int inProgrammerCode, int inFormID, int inFlashPeriod)

Calling this method causes the specified build button to flash. The flash period inFlashPeriod appears to be measured in milliseconds: the smaller the value, the quicker the flash; normally a value of 1000 is used. This method provides a useful way of alerting the player when a new building is available, or a hidden trade route is opened. We used this also during the Military Tutorial to flash the "Play Slow" button during an invasion:

    Int32 mIDSlow = IDMaker.FromString("Play speed slow");
    game.FlashUIControl(mIDSlow, Toolset.MainGameFormID, 1000);

LockUIControl(int inProgrammerCode, int inFormID)

This method locks the specified build button, which will prevent the player from building that particular structure. It would be used normally to disable a building until particular requirements are met.

The UI control has to be identified by its ID; for some buildings and other buttons, this can be obtained using the IDMaker.FromString() method. (In other cases they could only be obtained by 'brute force' using a custom script.) Note that there are a small number for which we have not been able to find an ID. Examples (locking the furniture and utensils factory buttons):

    Int32 mUIIDFurniture = IDMaker.FromString("FACTORY_FURNITURE");
    Int32 mUIIDUtensils = 246675851;
    game.LockUIControl(mUIIDFurniture, Toolset.MainGameFormID);
    game.LockUIControl(mUIIDUtensils, Toolset.MainGameFormID);

See Part 11 for a complete list of (known) UI build button IDs.

For the major buttons e.g. Government, there is a method in Tools.cs that can be used to lock/unlock these buttons. For example:

    Tools.LockUI((int)Toolset.UIID._Govt);

However, this method first requires a declaration of Toolset, and a call to Tools.Init following scenario start or load. If you want to lock/unlock these buttons during a scenario, it is probably easier to obtain the UI button IDs from IDMaker>FromString().

    private Toolset Tools;

It is also possible to lock buttons on the Advisor and Empire Map screens. For example, the following code snippet locks the 'Send Rome Gift' and 'Change Salary' buttons on the Imperial Advisor screen, and the 'Open Trade' button (for all trade routes) on the Empire Map:

    Int32 mUIIDRomeGift = 989726641;
    Int32 mUIIDSalary = 989726645;
    Int32 mUIIDOpenTrade = -520227242;
    game.LockUIControl(mUIIDRomeGift, Toolset.AdvisorsFormID);
    game.LockUIControl(mUIIDSalary, Toolset.AdvisorsFormID);
    game.LockUIControl(mUIIDOpenTrade, Toolset.EmpireLevelFormID);

If you are using the script to lock or unlock the build buttons based on triggers, you need to be aware that the state of the buttons (locked or unlocked) is not "remembered" when you save a game. On a scenario reload, all buttons that are made available through the editor will be available to the player unless you get the script to lock them again. Therefore, you will need a variable (typically a boolean flag) that you can use to keep track of whether a building is locked or unlocked. These need to be declared in the variable section at the start of the script. They can then be used in a function such as ResetBaseUI which is called on scenario start and load to set the UI controls in the required state.

You would include the following line in each of the OnScenarioLoad and OnBeginScenario methods.

    bInit = true;
    if (bInit)
    {
        ResetBaseUI(game);
        bInit = false;
    }

The reason for doing it this way (rather than calling ResetBaseUI from OnScenarioLoad and OnBeginScenario is that the locking and unlocking doesn't always seem to work, presumably because the UI button state has not been fully initialised. Finally the ResetBaseUI method would look something like this:

    void ResetBaseUI(IGameQueryInterface game)
    {
        if (!bCircus) game.LockUIControl(mUIIDCircus, Toolset.MainGameFormID);
    }

UnlockUIControl(int inProgrammerCode, int inFormID)

This unlocks the specified control, if it has previously been locked using the LockUIControl method as described above.

GetUIControlLocked(int inProgrammerCode, int inFormID, out bool outLocked)

Based on testing of this method, it seems to serve no useful purpose: the boolean flag outLocked appears to be returned as TRUE regardless.

GetUIControlUsed(int inProgrammerCode, int inFormID, out bool outUsed)

This method returns the boolean flag outUsed set to TRUE if the player has ever clicked on the identified build button at any point during the current session - even if the building was never placed. However, this state is not remembered across a save - when the save is reloaded then the flag will be returned as FALSE until such a time as the player clicks on the button again.

< Previous: Buildings and resources | Editor Guide | Next: Triggered events >