Symbol Commands

Symbol commands are used to create, manage, and insert symbols for reusing and sharing graphic elements. Symbols support saving to the server or local browser storage.

Symbol Concepts

A symbol is a collection of CAD entities that can be managed and inserted as an independent unit:

• Symbol Definition: Contains entity data, base point, thumbnail, and other information
• Symbol Category: Used to organize and manage symbols
• Storage Location: Supports server storage and local browser storage

Differences Between Symbols and Blocks

Feature	Symbol	Block
Storage method	Independent file (server/local)	Within drawing document
Sharing scope	Cross-document, cross-user	Current document only
Management	Category-based management	Block definition list
Insertion method	Merge entities into document	Insert block reference

---

INSERTSYMBOL - Insert Symbol

Selects a symbol from the symbol library and inserts it into the current drawing.

Command Name: INSERTSYMBOL

Usage

Command: INSERTSYMBOL

Opens the symbol selection dialog after execution.

Dialog Description

Three-column layout:

• Left: Category list (server categories and local categories displayed in groups)
• Center: Symbol grid (shows thumbnails and names, supports search and pagination)
• Right: Preview and insertion options

Insertion options:

• Allow Scale: When enabled, allows interactive specification of scale factor
• Allow Rotation: When enabled, allows interactive specification of rotation angle
• Insert at Original Coordinates: Inserts directly at the symbol's original coordinates without specifying an insertion point
• Clear Source Info: Clears entity objectId to remove version tracking information

Workflow

1. Select a category
2. Select a symbol (searchable, double-click for quick insertion)
3. Set insertion options
4. Click the "Insert" button
5. Specify the insertion point in the drawing
6. Optional: Specify scale factor (drag or enter value)
7. Optional: Specify rotation angle (drag or enter value)

Interactive Prompts

Specify insertion point: <Click or enter coordinates>
Specify scale factor or drag mouse <1.00>: <Drag/click/enter value/press Enter to confirm>
Specify rotation angle or drag mouse <0.0°>: <Drag/click/enter angle/press Enter to confirm>
Inserted n entities (Scale: x.xx, Rotation: xx.x°).

---

CREATESYMBOL - Create Symbol

Saves selected entities as a symbol.

Command Name: CREATESYMBOL

Usage

Command: CREATESYMBOL

If entities are currently selected, they will be automatically included; otherwise, you can select them in the dialog.

Dialog Description

Left form:

• Select Entities: Shows the selected count, supports "Select" and "Clear" buttons
• Symbol Name: Enter the name of the symbol
• Save Location: Choose "Server" or "Local"
• Category: Select target category, supports "New" category
• Clear Source Info: Clears entity objectId

Right preview:

• Shows a preview of the selected entities
• Supports enabling/disabling preview

Base point coordinates:

• X/Y coordinate input fields
• "Pick" button: Interactively pick the base point in the drawing

Workflow

1. Select entities to save (or use the current selection set)
2. Enter the symbol name
3. Choose the save location and category
4. Set the base point coordinates (can be picked)
5. Click the "Save" button

Data Processing

When creating a symbol, the system automatically:

• Collects layers, linetypes, text styles, and block definitions that the entities depend on
• Exports hatch pattern definitions
• Generates thumbnails
• Compresses data (for server storage)

---

MANAGESYMBOL - Manage Symbols

Opens the symbol management dialog to manage categories and symbols.

Command Name: MANAGESYMBOL

Usage

Command: MANAGESYMBOL

Dialog Description

Tabs:

• Server Symbols: Manage symbols stored on the server
• Local Symbols: Manage symbols stored in local browser storage

Three-column layout:

• Left: Category management (create, rename, delete categories)
• Center: Symbol list (search, pagination, delete symbols)
• Right: Symbol preview and detailed information

Category Management

Operation	Button	Permission Required
Create category	+	Server requires permission, local unrestricted
Rename category	✎	Server root only, local unrestricted
Delete category	×	Server root only, local unrestricted

Symbol Management

• Search: Search symbols by name
• Sort: Sort by time or name
• Delete: Select a symbol and click the delete button

Note

Deleting a category will also delete all symbols under that category. This operation cannot be undone.

---

Code Examples

Example 1: Create a Local Symbol

const { LineEnt, CircleEnt, Engine, getLocalStorageService, 
        buildSymbolVcadData, generateThumbnailFromEntities } = vjcad;

// 1. Create entities
const line1 = new LineEnt([-10, 0], [10, 0]);
const line2 = new LineEnt([0, -10], [0, 10]);
const circle = new CircleEnt([0, 0], 8);

line1.setDefaults();
line2.setDefaults();
circle.setDefaults();

// 2. Get local storage service
const localService = getLocalStorageService();

// 3. Create or get category
let categories = await localService.getLocalSymbolCategories();
let category = categories.find(c => c.name === "Example Symbols");
if (!category) {
    category = await localService.createLocalSymbolCategory("Example Symbols");
}

// 4. Build symbol data
const entities = [line1, line2, circle];
const vcadData = await buildSymbolVcadData(entities, false);

// 5. Generate thumbnail
const thumbnail = await generateThumbnailFromEntities(entities, 128, 128);

// 6. Save symbol
const symbol = await localService.saveLocalSymbol({
    categoryId: category.id,
    name: "Cross Circle Symbol",
    basePoint: [0, 0],
    thumbnail: thumbnail,
    vcadData: vcadData
});

console.log("Symbol saved:", symbol.id);

Example 2: Interactive Symbol Insertion

const { Engine, getLocalStorageService, insertSymbolInteractive } = vjcad;

// 1. Get symbol data
const localService = getLocalStorageService();
const categories = await localService.getLocalSymbolCategories();
const symbols = await localService.getLocalSymbolList(categories[0].id);
const symbolData = await localService.getLocalSymbol(symbols[0].id);

// 2. Interactive insertion
const entities = await insertSymbolInteractive(
    symbolData.vcadData,
    symbolData.basePoint,
    {
        allowScale: true,      // Allow scaling
        allowRotation: true,   // Allow rotation
        clearSourceInfo: false // Keep source info
    }
);

if (entities) {
    console.log("Insertion successful, entity count:", entities.length);
    Engine.zoomExtents();
}

Example 3: Direct Symbol Insertion (Non-interactive)

const { Engine, Point2D, getLocalStorageService, 
        parseSymbolVcadData, mergeSymbolToDocument } = vjcad;

// Get symbol
const localService = getLocalStorageService();
const symbolData = await localService.getLocalSymbol(symbolId);

// Parse symbol document
const symbolDoc = await parseSymbolVcadData(symbolData.vcadData);

// Insert directly at specified position
const insertPoint = new Point2D(100, 100);
const entities = mergeSymbolToDocument(
    symbolDoc,
    insertPoint,
    symbolData.basePoint,
    2.0,    // Scale 2x
    45,     // Rotate 45 degrees
    false   // Keep source info
);

Engine.regen();

---

Next Steps

• Symbol API Reference - Complete API documentation
• Block Commands - Block creation and management
• Command Reference - View all commands