MicroStation Connect Ribbonbar Toggle Buttons.

Hi Michael,

a common request: Please read and follow this forum best practices. Even when ribbon is neutral topic, how an answer can be provided when it's not clear what MicroStation version do you use (ribbon was enhanced in different versions) and also what API / language your "custom application" use?

Michael Gravel said:

I have a button on a custom ribbon bar

How your ribbon is defined? Is it created using Ribbon customize tool (I do not recommend to use this way for any serious professional development), using ribbon xml definition or even compiled to rsc file?

Michael Gravel said:

that I would like to act like a toggle.

Ribbon provide ToggleButton object that I assume should be used to "toggle", not plain button.

Michael Gravel said:

Is there an example that documents how this is accomplished by a custom application?

I do not remember whether I used Toggle button in the past, but it would be simple, because the toggle button object is "ready for it". I assume ToggleExpression defines symbol that is evaluated to find out whether the button is on or off, and SyncItemEvent (that can be raised by any application) defines when the expression to be evaluated.

In the chapter mentioned bellow, there are at least two examples of ToggleButton definition using xml.

Michael Gravel said:

Or, what topics would one would look under on the developers forum or in the MicroStation API help file.

See Ribbon Bar Interface chapter in MicroStation API documentation.

Regards,

  Jan

An update to my previous post

1. [CE U13 C++] 

2. I have a ribbon bar that is stored in a dgnlib file that is loaded at runtime. It was created via the Customize Ribbon dialog. 

3. I have an XML file that I contains the definition of a toggle button that is loaded at runtime and can be seen in the Customize Ribbon dialog. Note that for example seen below of a ribbon bar, “MichaelLabel, the entire ribbon bar was defined in the XML file.  However, adding it to the ribbon bar defined in the dgnlib file results in the same problem to be discussed below. 

4. In order to complete the definition of the toggle button in the XML file, A Sync Group Resource and a Named Expression were generated. Also I published a basic variable called, m_My2dSnapToggleEnabled, that was used in the Named Expression.  Note that invoking the “Test” button on the Named Expressions dialog returns TRUE or FALSE depending on the value of m_My2dSnapToggleEnabled variable, which is changed in the code when the, “ISSD 2dsnap”, command is executed using either the toggle button or via key in.  Furthermore, when the value of m_My2dSnapToggleEnabled is modified, I call DialogManager::SendUISyncMessage. 

5. Sync Group Resource Definition:

   SyncGroupRsc SYNCGROUPID_ISSDParamChanged =
   {
     "ISSDParamChanged",
     {
       { SYNCITEM_ISSDParamChanged_2dSnap,              "2dSnap"             }
     }
   }

6. Code to Synchronize the toggle button

   m_My2dSnapToggleEnabled = snapToggle;
	DialogManager::SendUISyncMessage(SYNCGROUPID_ISSDParamChanged, NULL,
                                    SYNCITEM_ISSDParamChanged_2dSnap);

7. Published Basic Variable:

	SymbolSet *SetP = mdlCExpression_initializeSet(VISIBILITY_DIALOG_BOX, 0, TRUE);
	mdlDialog_publishBasicVariable(SetP, mdlCExpression_getType(TYPECODE_INT), 
                 (char *)"m_My2dSnapToggleEnabled", &m_My2dSnapToggleEnabled);

8. Named Expression:
9. Toggle Button Definition in XML file (I tried inserting as XML and Text and it corrupted the information. Sorry): 

                 <ToggleButtons>

                    <ToggleButton Name="ISSD.Utilities.2dSnap" Priority="100">

                         <ToggleButtonParams Size="Large">

                             <AccessText />

                        </ToggleButtonParams>

                        <ToggleButtonData>

                            <CommandData Type="UserKeyinCommand">

                                <UserKeyinCommand>

                                    <Keyin>issd 2dsnap</Keyin>

                                    <Label>2D Snap</Label>

                                    <Description> Bla Blah Blah

                                    <ToggleExpression>[Session]Session.EvalCExprAsBool("m_My2dSnapToggleEnabled","")</ToggleExpression>

                                    <SyncItemEvent>ISSDParamChanged.2dSnap</SyncItemEvent>

                                    <Icon Type="NamedIcon">

                                        <NamedIcon>2d_snap</NamedIcon>

                                    </Icon>

                                </UserKeyinCommand>

                            </CommandData>

                        </ToggleButtonData>

                    </ToggleButton>

                </ToggleButtons>

Figure 1

My current problem is that the toggle button does not reflect the state based on the state/value of the named expression.  I am unsure whether the ToggleExpression is defined correctly or whether the SyncItemEvent is actually being registered or fired.  I suspect the latter because of the following error that I see in the Message Center window when I run Connect.  See Figure 2 below.  When "2d Snap" is On, the button should be depressed.  When "2d Snap" is off, it should not be depressed. Again, when on, the named expression evaluates to TRUE and when off, the named expression evaluates to FALSE.

There is a section in the Microstation API chm (Help file) if you search Introduction called, Application Provided Sync Group Resources.  Step 1 makes sense to me and I have added the Sync Group Resource to my resources as seen above.  However Step 2 is not clear to me.  We compile our resources using rcomp.exe and rlib.exe directly.  We do not use the BMake facility.  I have search through all API help, every file in the Bently delivered folders of Connect installaion and every file in the uStationConnectSDK folder structure and cannot find what or where this type of file exists.  This snippet is lost to me.  But it appears to be a missing piece in my workflow.  This configuration looking variable, MS_SYNCGROUP_APPS cannot be set in the Configuration Variables dialog in Connect.  Outside of this obscure snippet in the API help, how does one set this variable and what is supposed to be added to it.  My MDL application is housed in a DLL called issd.ma.

Figure 2

I have exhausted all my options at this point.  I cannot glean anymore information from the API help or online help.  I don't know what else I can do to  describe my situation other than create an application and all it's baggage and send to the forum.

  In my reply I mentioned a help section.  In that section a test app is mentioned.  Where can one find that test app?  Snippet from the section describing, poorly I might add, the test app: RibbonTestApp.

Michael Gravel said:

Where can one find that test app?

Good question!  The cited folder ..\MstnPlatform\mstn\testapps\ is not part of the MicroStation CONNECT delivered SDK.  It looks like an internal Bentley Systems location. RibbonTestApp is not among the examples delivered with the SDK.

Update on the configuration variable: MS_SYNCGROUP_APPS.  My application is housed in issd.ma.  I updated my issd.cfg file delivered at installation time to C:\Program Files\Bentley\MicroStation CONNECT Edition\MicroStation\config\appl, with the following line:  MS_SYNCGROUP_APPS > issd;  When my application runs, I use the following API call to read that configuration variable:

mdlSystem_getCfgVar(&wStr, L"MS_SYNCGROUP_APPS");

The value of wStr is "issd".  So, I would like to think my Sync Group Resource is loaded before the ribbonbar is loaded as the documentation suggest.  However, I still get the error as seen in Figure 2 above. That is, Unable to find UI Sync event named: ISSDParamChanged.2dSnap.

Again, seems that my understanding of the documentation is not complete.  Please advise.

Michael Gravel said:

Again, seems that my understanding of the documentation is not complete. 

I think your understanding of the documentation is complete, but what is not complete is the documentation itself.

Regards,

  Jan

Hi Michael,

a few more comments:

Michael Gravel said:

2. I have a ribbon bar that is stored in a dgnlib file that is loaded

I am not sure whether simple (and limited) dgnlib based customization can be used in this scenario. Also I have never tried to combine it with xml definition.

Michael Gravel said:

3. I have an XML file that I contains the definition of a toggle button

I think to use xml definition should be standard for any ribbon customization delivered with any application. There are some important advantages exist, at least it's pretty complete (comparing to limited functionality of dgnlib GUI customization tool) and it's simple to maintain the definition as a part of codebased (e.g. in Git).

My experience is quite good (even when the definition is often painful a bit ;-), especially because of extra functionality available.

Michael Gravel said:

In order to complete the definition of the toggle button in the XML file, A Sync Group Resource and a Named Expression were generated.

I have not tried to create own code with synchronized toggle button, but I am pretty sure Named Expression is not required for ribbon definition. It can be used, but I think it makes sense only when you would like to implement of Symbol Provider. Normally, to define complete expression inside XML file should be enough.

On the other hand, Named Expression can be used to check, whether your variable is published and visible properly.

Michael Gravel said:

However Step 2 is not clear to me

I agree this paragraph explains the topic in an over-complicated way and when not understood right, it can be misleading.

Michael Gravel said:

We compile our resources using rcomp.exe and rlib.exe directly.  We do not use the BMake facility.

I am not sure whether it's valid for the discussed issue, but to use bmake is preferred, because in mki files plenty of rules and settings are defined and prepared to be used automatically, often using specific setting pre-cooked for MicroStation.

Michael Gravel said:

I have search through all API help, every file in the Bently delivered folders of Connect installaion and every file in the uStationConnectSDK folder structure and cannot find what or where this type of file exists.

Actually, I think it's not about bmake file, because it's evidently XML file, whereas mke files are plain text files.

I think it's part of MSBuild proj file with instructions for Bentley.Build.Tasks. But I am pretty sure to use it is not mandatory, it only automates setting of MicroStation configuration variables (which allows to get closer to "infrastructure as code" concept, allowing to maintain everything in codebase).

Michael Gravel said:

This configuration looking variable, MS_SYNCGROUP_APPS cannot be set in the Configuration Variables dialog in Connect.

It's not expected application variable will be set manually in MicroStation GUI, especially because it's stored in user configuration file and as such processed quite lately when MicroStation starts.

Michael Gravel said:

how does one set this variable and what is supposed to be added to it.

Exactly as you did: To add own configuration file to \config\appl\ folder. It's expected installer will do it when the application is installed.

Michael Gravel said:

However, I still get the error as seen in Figure 2 above. That is, Unable to find UI Sync event named: ISSDParamChanged.2dSnap.

Unfortunately it's not clear what part of MicroStation fires this error.

Can you try to remove the ribbon customization to check whether the error will be still reported? Because when not, it (I think) means ribbon engine cannot find the synchronization group and .rsc file is not prepared properly (misnaming, wrongly compiled, loaded after the ribbon ...).

In general, you should isolate parts and to test, whether they work fine. Maybe it's only about both side are fine, but "a connection" does not work.

With regards,

  Jan

Hi Michael,

a few more comments:

Michael Gravel said:

2. I have a ribbon bar that is stored in a dgnlib file that is loaded

I am not sure whether simple (and limited) dgnlib based customization can be used in this scenario. Also I have never tried to combine it with xml definition.

Michael Gravel said:

3. I have an XML file that I contains the definition of a toggle button

I think to use xml definition should be standard for any ribbon customization delivered with any application. There are some important advantages exist, at least it's pretty complete (comparing to limited functionality of dgnlib GUI customization tool) and it's simple to maintain the definition as a part of codebased (e.g. in Git).

My experience is quite good (even when the definition is often painful a bit ;-), especially because of extra functionality available.

Michael Gravel said:

In order to complete the definition of the toggle button in the XML file, A Sync Group Resource and a Named Expression were generated.

I have not tried to create own code with synchronized toggle button, but I am pretty sure Named Expression is not required for ribbon definition. It can be used, but I think it makes sense only when you would like to implement of Symbol Provider. Normally, to define complete expression inside XML file should be enough.

On the other hand, Named Expression can be used to check, whether your variable is published and visible properly.

Michael Gravel said:

However Step 2 is not clear to me

I agree this paragraph explains the topic in an over-complicated way and when not understood right, it can be misleading.

Michael Gravel said:

We compile our resources using rcomp.exe and rlib.exe directly.  We do not use the BMake facility.

I am not sure whether it's valid for the discussed issue, but to use bmake is preferred, because in mki files plenty of rules and settings are defined and prepared to be used automatically, often using specific setting pre-cooked for MicroStation.

Michael Gravel said:

I have search through all API help, every file in the Bently delivered folders of Connect installaion and every file in the uStationConnectSDK folder structure and cannot find what or where this type of file exists.

Actually, I think it's not about bmake file, because it's evidently XML file, whereas mke files are plain text files.

I think it's part of MSBuild proj file with instructions for Bentley.Build.Tasks. But I am pretty sure to use it is not mandatory, it only automates setting of MicroStation configuration variables (which allows to get closer to "infrastructure as code" concept, allowing to maintain everything in codebase).

Michael Gravel said:

This configuration looking variable, MS_SYNCGROUP_APPS cannot be set in the Configuration Variables dialog in Connect.

It's not expected application variable will be set manually in MicroStation GUI, especially because it's stored in user configuration file and as such processed quite lately when MicroStation starts.

Michael Gravel said:

how does one set this variable and what is supposed to be added to it.

Exactly as you did: To add own configuration file to \config\appl\ folder. It's expected installer will do it when the application is installed.

Michael Gravel said:

However, I still get the error as seen in Figure 2 above. That is, Unable to find UI Sync event named: ISSDParamChanged.2dSnap.

Unfortunately it's not clear what part of MicroStation fires this error.

Can you try to remove the ribbon customization to check whether the error will be still reported? Because when not, it (I think) means ribbon engine cannot find the synchronization group and .rsc file is not prepared properly (misnaming, wrongly compiled, loaded after the ribbon ...).

In general, you should isolate parts and to test, whether they work fine. Maybe it's only about both side are fine, but "a connection" does not work.

With regards,

  Jan