UI Standards

Use the following to train your LLM on the UI specific coding standards for Launchpad scripts.

UI Coding Standards for Launchpad Scripts

Naming Conventions

1. UI Elements

   • Create a string variable for all tool labels. Use the variable to create the control

   • Use descriptive label names with "Label" suffix: wallTypeLabel

   • Use consistent naming for form result retrieval: results.GetStringResult(myLabel)

UI Design

1. Forms and Controls

   • Create logical groupings of related controls

   • Use consistent padding and spacing

   • Add descriptive labels and headers

   • Include help links where appropriate

   • Limit form size to reasonable dimensions (e.g., 800x700 max)

2. DataGrids

   • Define column widths proportionally

   • Make read-only columns visually distinct

   • Use appropriate controls for editing (e.g., ComboBox for selection)

   • Add sorting and filtering capabilities where helpful

Form Creation

1. Form Types and Usage

   • Use CreateCustomForm() for user input forms requiring OK/Cancel actions

   • Use CreateInfoForm() for read-only displays with only a Close button

   • Set appropriate width/height based on content (typically 400-600 width, 300-800 height)

   • Always provide descriptive window titles

2. Form Builder Pattern

   var result = CreateCustomForm("Form Title", 500, 400, form => {
       // Add controls here
       form.AddHeader("Section Title");
       form.AddTextInput(labelVariable, "default value");
   });

Control Organization

1. Grouping Controls

   • Use BeginGroupBox()/EndGroupBox() for related controls

   • Use BeginExpander()/EndExpander() for optional/advanced settings

   • Set includeScrollbar: true for GroupBoxes with many controls

   • Use consistent margins (typically 5-10) between groups

2. Headers and Labels

   • Use AddHeader() for major sections (default fontSize: 16)

   • Use AddLabel() for descriptive text and instructions

   • Apply isBold: true for important labels

   • Use isItalic: true for supplementary information

Input Control Standards

1. Text Input

   string nameLabel = "Element Name:";
   form.AddTextInput(nameLabel, defaultValue: "", isEnabled: true);

   • Always provide meaningful default values when possible

   • Disable controls that should be read-only with isEnabled: false

2. Selection Controls

   • ComboBox: Use for single selection from predefined lists

     form.AddComboBox(wallTypeLabel, wallTypes, 
         wt => wt.Name, 
         currentWallType);

   • ListBox: Use for multiple selections or when showing more items at once

     form.AddListBox(categoriesLabel, categories, 
         c => c.Name,
         true,
         height: 150);

   • RadioButtons: Use for 2-5 mutually exclusive options

     form.AddRadioButtons(placementLabel, 
         new List<string> { "Center", "Start", "End" },
         defaultSelected: "Center");

3. Boolean Controls

   • Use AddCheckbox() for independent on/off settings

   • Set meaningful default states based on common usage

4. Numeric Input

   • Use AddSlider() for bounded numeric ranges

   form.AddSlider(offsetLabel, 
       minimum: 0, 
       maximum: 100, 
       value: 50,
       tickFrequency: 10,
       showValue: true);

5. File Selection

   • Use AddFileSelector() for single file selection

   • Use AddMultiFileSelector() for multiple files

   • Provide appropriate file filters:

     form.AddFileSelector(fileLabel, "Excel Files (*.xlsx)|*.xlsx|All files (*.*)|*.*");

Form Result Handling

1. Result Retrieval Pattern

   var result = CreateCustomForm("Title", 500, 400, form => {
       form.AddTextInput(nameLabel);
       form.AddComboBox(typeLabel, types);
   });
   
   if (!result.WasConfirmed) return;
   
   string name = result.GetStringResult(nameLabel);
   var selectedType = result.GetResult<WallType>(typeLabel);

2. Validation

   • Check result.WasConfirmed before processing

   • Validate retrieved values before use

   • Handle null/empty results appropriately

Progress and Feedback

1. Progress Bar Usage

   StartProgressBar(elements.Count, "elements", showCancelButton: true);
   
   for (int i = 0; i < elements.Count; i++)
   {
       if (IsProgressCancelled()) break;
       
       UpdateProgressBar(i, $"Processing {elements[i].Name}");
       // Process element
   }
   
   EndProgressBar();

2. Timer Usage

   StartTimer();
   // Perform operations
   var elapsed = StopTimer("Data Processing", outputToConsole: true);

Element Selection

1. Single Element Selection

   var element = SelectElement(uidoc, "Select a wall:");
   if (element == null) return;

2. Category-Specific Selection

   var wall = SelectElementByCategory(uidoc, "Walls", "Select a wall element:");

3. Multiple Element Selection

   var elements = SelectElements(uidoc, "Select elements to process:");
   if (!elements.Any()) return;

4. ** Select Point**

   XYZ startPoint = uidoc.Selection.PickPoint("Select start point");
   XYZ endPoint = uidoc.Selection.PickPoint("Select end point");

Best Practices

1. Label Variables

   • Always create string variables for all labels

   • Use descriptive names with context

   string wallTypeLabel = "Wall Type:";
   string levelLabel = "Target Level:";
   string offsetLabel = "Offset Distance:";

2. Display Selectors

   • Always provide displaySelector functions for complex types

   • Return meaningful display strings (typically the Name property)

   displaySelector: item => item.Name

3. Error Handling

   • Check for null results from selection methods

   • Validate form inputs before processing

   • Use try-catch blocks around form operations

4. Performance

   • Use progress bars for operations on 10+ elements

   • Update progress at reasonable intervals (not every iteration for large sets)

   • Allow cancellation for long-running operations

5. Consistency

   • Maintain consistent control order across similar forms

   • Use the same labels for the same concepts throughout scripts

   • Follow Revit's terminology and conventions

UI Layout Guidelines

1. Control Order

   • Required fields first, optional fields last

   • Group related inputs together

   • Place action-triggering controls (buttons, links) at the bottom

2. Sizing Recommendations

   • Headers: fontSize 16-20 for main sections

   • Labels: fontSize 11 (default) for standard text

   • ListBox height: 100-200 pixels depending on content

   • Form width: 400-600 pixels for most forms

   • Form height: Adjust based on content, avoid scrolling when possible

3. Expander Usage

   • Use for advanced options that most users won't need

   • Set isExpanded: false by default

   • Include clear header text indicating what's inside

   • Set contentIndent: 15 for visual hierarchy

By following these standards, Launchpad scripts will provide consistent, intuitive user interfaces that align with both Revit conventions and user expectations.