How to Integrate TMS Metro Controls Pack with Your Project

Troubleshooting Common Issues in the TMS Metro Controls Pack

The TMS Metro Controls Pack provides modern, Metro-style UI components for Delphi and C++Builder applications. When integrating it into projects you may encounter common issues ranging from installation problems to runtime behavior and styling inconsistencies. This guide lists typical problems, root causes, and step-by-step fixes to get your app back to a polished Metro look quickly.

1. Installation & Licensing Problems

• Symptom: Components do not appear on the IDE component palette after installation.
  • Cause: Package not registered, IDE path mismatch, or license key not applied.
  • Fix:
    1. Run the installer as Administrator.
    2. Ensure the IDE version matches the package (check IDE support in TMS documentation).
    3. In Delphi/C++Builder, go to Component > Install Packages and verify the TMS packages are checked. If missing, use “Add” to load the .bpl files from the install folder.
    4. Apply license key via the TMS License Manager or follow the provided activation steps.
• Symptom: “License invalid” or trial expired errors.
  • Cause: License file not found or installation used a different user account.
  • Fix: Re-enter license details in License Manager, copy license file to the IDE’s expected folder, or contact TMS support with purchase receipt.

2. Design-Time Errors or IDE Crashes

• Symptom: IDE crashes when opening forms containing TMS Metro controls.
  • Cause: Conflicting installed packages or corrupted package files.
  • Fix:
    1. Remove recently installed or suspicious packages via Component > Install Packages.
    2. Rebuild TMS packages: open the package project (.dpk/.bpk) matching your IDE, compile and install it again.
    3. Clear IDE cache and temporary files; restart IDE.
• Symptom: Property editor missing or shows exceptions.
  • Cause: Outdated design-time package or mismatched Delphi version.
  • Fix: Install the correct design-time package version bundled for your IDE release.

3. Styling and Theme Inconsistencies

• Symptom: Controls render with default (VCL) style instead of Metro theme.
  • Cause: Theme not applied at runtime or application uses incompatible VCL styles.
  • Fix:
    1. Ensure you include and initialize the TMS Metro style manager component (e.g., TTMSStyleRepository / TTMSMetroStyleManager) and set the desired theme at startup.
    2. For VCL style conflicts, either disable conflicting styles or use TMS theme-compatible styles. Check TMS docs for supported styles.
• Symptom: Inconsistent fonts, spacing, or control sizes.
  • Cause: DPI scaling or font settings differ between design-time and runtime.
  • Fix:
    1. Enable High DPI awareness in project options and test at target DPI.
    2. Use Anchors and Align properties rather than fixed sizes; verify scaling behavior in form’s OnCreate by adjusting fonts programmatically if needed.

4. Runtime Exceptions or Unexpected Behavior

• Symptom: Access violations when showing forms with TMS Metro controls.
  • Cause: Version mismatch between runtime and design-time packages or missing runtime packages.
  • Fix:
    1. Verify all required runtime .bpl/.dcu files are deployed with the application.
    2. Rebuild the project against the installed TMS runtime packages.
    3. Check event handlers and custom drawing code for null references.
• Symptom: Controls not responding to input events (clicks, keyboard).
  • Cause: Another transparent control overlaying TMS controls, or wrong TabOrder/Enabled settings.
  • Fix: Use IDE form view to inspect Z-order (Send to Back/Bring to Front), confirm Enabled/Visible properties, and test without third-party overlays.

5. Performance Issues

• Symptom: UI is sluggish when using complex TMS Metro controls.
  • Cause: Excessive custom painting, too many controls, or heavy data-bound operations on the UI thread.
  • Fix:
    1. Profile and reduce custom OnDraw/OnPaint work; cache graphics where possible.
    2. Virtualize lists/grids or use paging for large datasets.
    3. Move heavy computations or data fetches to background threads (TTask/TThread) and synchronize updates to the UI afterward.
    4. Disable unnecessary animations or effects if targeting lower-power machines.

6. Data Binding and Grid Issues

• Symptom: Grid does not update when underlying dataset changes.
  • Cause: Missing notifications or dataset not in the proper state.
  • Fix:
    1. Ensure dataset’s events (AfterPost/AfterEdit) call Refresh or use LiveBindings properly.
    2. For Virtual/Owner-draw modes, call InvalidateGrid or RefreshGrid methods after data changes.
• Symptom: Sorting/filtering not applied as expected.
  • Cause: Using client-side datasets without proper index or filter application.
  • Fix: Apply filtering via dataset.Filter and Filtered := True or use grid’s built-in sorting when connected to providers that support it.

7. Printing and Exporting Problems

• Symptom: Exported PDF or printed output’s styling differs from on-screen appearance.
  • Cause: Export routines use different rendering path or lack style resource mapping.
  • Fix:
    1. Use TMS-provided export/print components/methods that preserve styling.
    2. Ensure fonts used are embedded or available on the target system.
    3. For custom exports, reproduce style settings in the export renderer.

8. Integration with Third-Party Libraries

• Symptom: Conflicts with other UI component libraries (e.g., overlapping palettes, runtime clashes).
  • Cause: Duplicate component names, package GUID conflicts, or shared resource identifiers.
  • Fix:
    1. Install packages in isolation to identify conflicts.
    2. Use namespace prefixes or adjust package load order.
    3. Contact both vendors if GUID/package conflicts are suspected.

9. Mobile or Cross-Platform Deployment Issues (if using FMX)

• Symptom: Controls behave differently on iOS/Android compared to Windows.
  • Cause: Platform-specific styles, touch handling, or unsupported features.
  • Fix:
    1. Test on real devices and adjust touch event handling.
    2. Use platform conditional code to adapt layouts and behavior.
    3. Refer to TMS FMX-specific documentation for supported controls and limitations.

10. When All Else Fails

• Checklist before contacting support:
  1. Reproduce the issue in a minimal sample project.
  2. Note Delphi/C++Builder version, TMS Metro Controls Pack version, OS, and steps to reproduce.
  3. Collect log files, exception call stacks, and screenshots.
• How to contact TMS support: Use TMS support channels (support ticket, forums) and attach the minimal sample and diagnostic info.

Quick Troubleshooting Flow (Summary)

1. Verify package installation and license.
2. Match design-time and runtime package versions.
3. Apply Metro theme and check DPI/scaling.
4. Inspect Z-order, Enabled/Visible, and event handlers for interaction issues.
5. Profile performance; move heavy work off the UI thread.
6. Reproduce in minimal project before contacting support.

If you want, I can produce a minimal Delphi sample project that reproduces a specific issue (e.g., theme not applying or access violation) — tell me which problem to demonstrate and I’ll provide code and steps.