CATNls/CATRsc resources generation |
| Technical Article |
AbstractThe purpose of this article is to explain how the designer handles the generation of the CATNls/CATRsc resources files. |
The generation of CATNls/CATRsc files is automatically activated when a new file is created.
Once the file is created, the feature can be activated or deactivated using the ‘File infos’ tab in the design view of the edited document, checking the ‘Use CATNls/CATRsc resources’ option:

In particular, this technique can be used to activate the export of resources in DSGen files created with a previous version of IDD that didn’t support the automatic resources generation.
File creation or feature activation :
In this case if no resources file is detected, we created them in the CNext/resources/msgcatalog directory (the directory is also created if it doesn’t exist).
If the CATNls and CATRsc files are found, we merge the DSGen data and the CATNls/CATRsc data. If a conflict between the files is detected, the designer asks the source that should be used to load resources. A conflict happens only if a property value is defined in both CATNls/CATRsc files and the DSGen file, and their values don’t match. After this optional export operation, the resources data will always be read from the CATNls/CATRsc files.

File with the feature activated opening :
When a file with this feature activated is opened, the resources files must exist, otherwise the resources edition will be locked. We use this strategy to avoid creating new CATNls/CATRsc files that may have been created earlier but deleted or moved. In this case, you must restore the CATNls/CATRsc files.
CATNls/CATRsc files loading :
The editor searchs for the CATNls and CATRsc files in every CNext* directories. If the files can be found in several directories, we signal the problem, and prevent any edition impacting the CATNls and CATRsc files in the designer. Since we can only control one set of resources files, we prevent the automatic edition of the resources files if several are detected, to avoid desynchronizations.
The resources files are then parsed, and the dialog properties values defined in those files are imported in the DSGen file model. The manually entered key/value entries and comments are also imported and will be regenerated by the designer when it will update the CATNls/CATRsc files.
Loading failure:
If the loading of the CATNls/CATRsc files fails, we still mark the feature as activated, but we lock the resources edition and some operations that may modify the resources files: widgets creation, deletion, move and name change. We display the error that occurred that should be resolved. Once corrected, the document must be reloaded to be able to fully edit the design of the dialog box.
In this sample, we see the error message displayed in the designer, and we see that the 'Name' and resources properties are not editable.

Feature deactivation:
If the resources export feature is deactivated, the last version of the external resources is left in the DSGen model. We ensure this way that no design data is lost when the feature is deactivated.
Resources generation:
If the designer generates the designed widget resources, we guarantee that the items in the generated CATNls and CATRsc files will have a stable order. Items that were already in the file will keep the same location (even if the key name may change due to a widget displacement or renaming), and the new keys will be added at the end of the files. This is also valid for comments or keys added manually. This will simplify potential merges on the CATNls/CATRsc files.
Remark : The feature will not handle the rename or move operation on the CATNls and CATRsc files automatically if the DSGen file is renamed or moved. Those files might be controlled by a source code manager, and the move operation could require some specific manual interactions.
The following textual and iconic resources will be written in the resources files, for every widget created in the designer:
Properties in the ‘Text Resources’ category:
Accelerator
Help
LongHelp
ShortHelp
Title
Properties in the ‘Icons’ category:
IconFocussed
IconNormal
IconSelected
Edition of the CATNls file in Visual Studio:
The CATNls files may contain keys entries that are entered manually (like Combo box items). The designer can load those data and preserve them, while automatically editing the resources that correspond to widget’s properties. Moreover, we support the concurrent edition of the resources files and the resources data in the designer if the files are opened in the same instance of Visual Studio. We provide the same feature on the CATRsc files to have a consistent behavior on those resources files handling, although those files don’t need to be edited manually.
When the DSGen and the CATNls files are opened, we don’t use the resources files on disk anymore, but the in-memory representation of the CATNls file loaded in Visual Studio.
When the DSGen file is modified (but not necessarily saved), we update the CATNls file document in Visual Studio.
When the CATNls file is modified in Visual Studio, we will use these modifications, even if the file isn’t saved after modification. After the modification in the Visual Studio document, we read this modification, and keep it as the current state of the CATNls file in the designer controller. When the DSGen file gains the focus (by becoming the active document), we will reload the resources from the last state read in the Visual Studio document. In particular, if the CATNls file is modified in Visual Studio and then closed, we keep in the designer the last state of the file in the Visual Studio document, even if the file isn’t saved. We do this to ensure that the modification done by the designer will be preserved when the CATNls file is closed. However, if you close the DSGen file without saving, or if you deactivate the CATNls export, this current state is lost.
Edition of the CATNls file in an other editor:
We listen to the system notifications on the CATNls file change. If this file is modified by another editor, we will handle the modification when the DSGen document retrieves the focus, or when the system indicate the file change if it already has the focus. In this case, we signal the file change, asking whether the designer should reload the file or ignore the modification.
We do this only when the CATNls file isn’t already opened in Visual Studio. Otherwise, Visual Studio will automatically handle the reloading of the file if their content is modified by another editor.
When Visual Studio controls the CATNls file reloading :

When we control the CATNls file reloading :

Remark: When a modification is done in the CATNls file (in Visual Studio or in another editor), the undo/redo stack is discarded in the designer.
When the feature is activated, the simulator will also load the resources properties from the CATNls/CATRsc files. There is no need to update the runtime view before launching the simulator.
Activating the Virtual NLS mode:
In order to check the behavior of the dialog box at runtime in languages other that English, we add the capability to activate the Virtual NLS mode in the simulator, that is the standard process used to perform this validation. The design contextual menu will have an additional item that will allow the activation/deactivation of this mode. When it’s activated, we will export the CATNlsTest environment variable before starting the simulator, so that the runtime code will read the NLS Test data generated by mkmk instead of the real CATNls file.

If this mode is activated, we check before launching the simulator that the NLS Test file is up-to-date. If the generated NLS Test file is older than the original CATNls file, we show a warning advising to rebuild the framework containing the dialog box. However, the simulator is still launched in this case.

When the simulator is launched in this mode, its will automatically load the NLS Test data that can be used to perform the validation of the dialog box in languages other than English. Here we see the design of the dialog box on the left, and the simulation with Virtual NLS data on the right.

When the feature is activated, the code generation is updated in order to load the resources from the CATNls/CATRsc files at runtime:
Remark: The designer will not update the runtime view automatically. Before executing a dialog box with this feature activated, you must call the Create Runtime View command.
| Version: 1 [Jun 2008] | Document created |