### Configure and Retrieve PlantUML Settings

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/05-settings-configuration.md

Example of how to get PlantUML settings instance, check rendering mode, configure rendering delay and encoding, and retrieve effective values.

```java
PlantUmlSettings settings = PlantUmlSettings.getInstance();

// Check rendering mode
if (settings.isRemoteRendering()) {
    String serverUrl = settings.getServerPrefix();
    System.out.println("Using remote server: " + serverUrl);
} else {
    String dotPath = settings.getDotExecutable();
    System.out.println("Using local rendering, Graphviz at: " + dotPath);
}

// Configure rendering
settings.setRenderDelay("200");  // 200ms delay
settings.setEncoding("ISO-8859-1");
settings.setIncludedPaths("/path1\n/path2");  // Multiline paths

// Get effective values
int delay = settings.getRenderDelayAsInt();
List<String> config = settings.getConfigAsList();
ImageFormat defaultFormat = settings.getDefaultExportFileFormatEnum();
```

--------------------------------

### RenderRequest Example Usage

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Demonstrates how to create a RenderRequest object and use it to render a PlantUML diagram.

```APIDOC
## RenderRequest Example Usage

### Description
Demonstrates how to create a RenderRequest object and use it to render a PlantUML diagram.

### Code Example
```java
Zoom zoom = new Zoom(100, settings); // 100% zoom
RenderRequest request = new RenderRequest(
    "/project/diagram.puml",
    "@startuml\nClass A\n@enduml",
    ImageFormat.SVG,
    0,
    zoom,
    1,
    true,
    RenderCommand.Reason.CARET,
    project
);

RenderResult result = PlantUmlFacade.get().render(request, null);
```
```

--------------------------------

### RenderCommand.Reason Usage Example

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/06-types.md

Demonstrates how to check the reason for a render request to handle specific scenarios like changes in included files.

```java
if (renderRequest.getReason() == RenderCommand.Reason.INCLUDES) {
    // Handle include file changes
}
```

--------------------------------

### Zoom Class Initialization Example

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/06-types.md

Demonstrates creating a Zoom object with a specified user zoom level and then retrieving the calculated display zoom, which accounts for system DPI scaling.

```java
Zoom zoom = new Zoom(null, 150, settings);  // 150% user zoom
int displayZoom = zoom.getScaledZoom();  // 300 on Retina (150 * 2.0 system scale)
```

--------------------------------

### Example Usage of RenderRequest

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Demonstrates how to instantiate a RenderRequest with specific parameters and then use it to render a PlantUML diagram via PlantUmlFacade. Ensure you have a valid Project instance and settings for Zoom.

```java
Zoom zoom = new Zoom(100, settings); // 100% zoom
RenderRequest request = new RenderRequest(
    "/project/diagram.puml",
    "@startuml\nClass A\n@enduml",
    ImageFormat.SVG,
    0,
    zoom,
    1,
    true,
    RenderCommand.Reason.CARET,
    project
);

RenderResult result = PlantUmlFacade.get().render(request, null);
```

--------------------------------

### Get PlantUML Facade Instance

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/00-index.md

Obtain the main facade for rendering PlantUML diagrams. This is the primary entry point for rendering operations.

```java
PlantUmlFacade facade = PlantUmlFacade.get();
RenderResult result = facade.render(renderRequest, cachedItem);
```

--------------------------------

### Generate and Share PlantUML Server Link

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

This example demonstrates how to encode PlantUML source code into a server-friendly URL and copy it to the system clipboard. It uses the configured server prefix and link type.

```java
PlantUmlFacade facade = PlantUmlFacade.get();
String source = "@startuml\nClass A\n@enduml";

try {
    String encoded = facade.encode(source);
    String server = settings.getServerPrefix();
    String linkType = settings.getServerClipboardLinkType();  // "uml", "png", "svg"
    
    String url = server + "/" + linkType + "/" + encoded;
    System.out.println("Share link: " + url);
    
    // Copy to clipboard
    StringSelection selection = new StringSelection(url);
    Toolkit.getDefaultToolkit()
        .getSystemClipboard()
        .setContents(selection, null);
        
} catch (IOException e) {
    System.err.println("Failed to encode: " + e.getMessage());
}
```

--------------------------------

### Example of PlantUML Source Encoding and URL Generation

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/10-remote-rendering.md

Demonstrates encoding a simple PlantUML diagram source and constructing a URL for remote rendering. The encoded string is appended to the base PlantUML server URL.

```java
String source = "@startuml\nClass A\n@enduml";
String encoded = facade.encode(source);  // "IowUY5xDx00pAnRzVN0cAIV..."
String url = "https://www.plantuml.com/plantuml/svg/" + encoded;
```

--------------------------------

### Skin Parameters

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Get a collection of available PlantUML skin parameter names that can be used for customization.

```APIDOC
## Skin Parameters

### Method
`getSkinParams()`

### Returns
`Collection<String>` - Available PlantUML skin parameter names
```

--------------------------------

### Render Diagram and Get Result

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Orchestrates diagram rendering with automatic strategy selection. Use this to get the rendered image bytes for display or further processing.

```java
RenderResult result = PlantUmlRendererUtil.render(renderRequest, cachedItem);
if (!result.hasError()) {
    for (ImageItem item : result.getImageItems()) {
        // Use item.getImageBytes()
    }
}
```

--------------------------------

### Get Available Skin Parameters

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Retrieve a collection of available PlantUML skin parameter names that can be used for customization.

```java
Collection<String> skinParams = facade.getSkinParams();
```

--------------------------------

### ImageFormat Enum Parsing Example

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/06-types.md

Demonstrates how to parse an ImageFormat enum from a string. Defaults to PNG if the input string does not match any defined format.

```java
ImageFormat fmt = ImageFormat.from("SVG");  // Returns SVG
ImageFormat fmt2 = ImageFormat.from("unknown");  // Returns PNG
```

--------------------------------

### Get Singleton PlantUML Facade Instance

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Obtain the singleton instance of the PlantUML facade. This instance is used to access all other facade methods.

```java
PlantUmlFacade facade = PlantUmlFacade.get();
```

--------------------------------

### Example Usage of RenderResult

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Demonstrates how to process a RenderResult object, check for errors, access rendered images, and display rendering statistics. This snippet shows common patterns for handling rendering outcomes.

```java
RenderResult result = PlantUmlFacade.get().render(request, cachedItem);

if (result.hasError()) {
    // Handle error case
    for (ImageItem item : result.getImageItems()) {
        if (item.hasError()) {
            Throwable e = item.getException();
            // Process error
        }
    }
} else {
    // Use rendered diagrams
    for (ImageItem item : result.getImageItems()) {
        byte[] pngBytes = item.getImageBytes();
        // Display or save
    }
}

System.out.println("Rendered: " + result.getRendered() + 
                   ", Cached: " + result.getCached() + 
                   ", Pages: " + result.getPages());
```

--------------------------------

### LinkData Usage Example

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/06-types.md

Iterates through a list of LinkData objects obtained from an image item. It checks if each item is a hyperlink and prints its text and click area if it is.

```java
List<LinkData> links = imageItem.getLinks();
for (LinkData link : links) {
    if (link.isLink()) {
        System.out.println("Link: " + link.getText() + " at " + link.getClickArea());
    }
}
```

--------------------------------

### Render Diagram Remotely

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/10-remote-rendering.md

Renders a diagram via an HTTP request to a PlantUML server. Use this when Graphviz is not installed or to offload rendering.

```java
public static RenderResult render(RenderRequest renderRequest)
```

--------------------------------

### Handle PlantUML Link Navigation Data

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

This example demonstrates how to retrieve and process link data associated with image items in a PlantUML render result. It iterates through links to extract URLs and their corresponding clickable regions.

```java
ImageItem item = result.getImageItem(0);
List<ImageItem.LinkData> links = item.getLinks();

for (ImageItem.LinkData link : links) {
    if (link.isLink()) {
        String url = link.getText();
        Rectangle region = link.getClickArea();
        
        // Handle click in region
        System.out.println("Link: " + url + " at " + region);
    }
}
```

--------------------------------

### Get PlantUML Version

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Retrieve the version string of the PlantUML library being used.

```java
String version = facade.version();
```

--------------------------------

### Rendering Utilities - PlantUmlRendererUtil

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/00-index.md

Core utilities for orchestrating rendering processes and setting up the environment. Includes methods for initiating rendering, saving to files, and managing rendering strategies.

```APIDOC
## PlantUmlRendererUtil

### Description
Core rendering orchestration and environment setup.

### Methods
- Main rendering entry: `render(RenderRequest, RenderCacheItem)`
- Save to file: `renderAndSave(RenderRequest, String, String)`
- SourceStringReader creation
- Strategy selection (Normal vs Partial)

### Related Utilities
- Adapter Utils (Environment preparation, directory management, PlantUML options, version retrieval, document saving)
- DiagramFactory (Creating Diagram objects, filename generation, page counting)
- Rendering Strategies (Normal, Partial, Error handling)
```

--------------------------------

### Minimal PlantUML Rendering in Java

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Demonstrates the most basic way to render a PlantUML diagram using the facade. Requires obtaining the facade instance and creating a RenderRequest object.

```java
PlantUmlFacade facade = PlantUmlFacade.get();

String source = "@startuml\nClass A\nClass B\nA --> B\n@enduml";
Zoom zoom = new Zoom(100, PlantUmlSettings.getInstance());

RenderRequest request = new RenderRequest(
    "/tmp/diagram.puml",           // sourceFilePath
    source,                         // PlantUML source
    ImageFormat.PNG,               // format
    0,                             // page (0-based)
    zoom,                          // zoom level
    1,                             // version
    true,                          // renderUrlLinks
    RenderCommand.Reason.MANUAL_UPDATE,
    null                           // project (can be null)
);

RenderResult result = facade.render(request, null);  // null = no cache

if (!result.hasError()) {
    for (ImageItem item : result.getImageItems()) {
        byte[] pngBytes = item.getImageBytes();
        // Save or display
    }
}
```

--------------------------------

### Get PlantUmlApplicationComponent Name

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/11-plugin-components.md

Returns the component name, used internally by the IntelliJ platform for component management.

```java
String getComponentName()
```

--------------------------------

### Get Auto-Generated Filename

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Determine an auto-generated filename for a PlantUML diagram based on the project, source, and virtual file.

```java
String filename = facade.getFilename(project, source, virtualFile);
```

--------------------------------

### Main Rendering Entry Point

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Orchestrates diagram rendering with automatic strategy selection. It prepares the PlantUML environment, splits the source into pages, detects partial rendering, selects the appropriate renderer (partial or normal), and returns the render result.

```APIDOC
## render

### Description
Orchestrates diagram rendering with automatic strategy selection.

### Method
```java
public static RenderResult render(RenderRequest renderRequest, RenderCacheItem cachedItem)
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **renderRequest** (RenderRequest) - Required - Render parameters (source, format, zoom, etc.)
- **cachedItem** (RenderCacheItem) - Required - Previous render result for cache validation

### Response
#### Success Response (200)
- **RenderResult** - Contains rendered diagrams for all pages.

#### Response Example
```java
RenderResult result = PlantUmlRendererUtil.render(renderRequest, cachedItem);
if (!result.hasError()) {
    for (ImageItem item : result.getImageItems()) {
        // Use item.getImageBytes()
    }
}
```
```

--------------------------------

### PlantUML Pagination with Cache in Java

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Demonstrates how to handle paginated PlantUML diagrams using the cache. It shows how to request a specific page and utilize the cache for unchanged pages.

```java
// Get page count from previous render
RenderCacheItem cached = ...;
int pageCount = cached.getRenderResult().getPages();

// Request specific page
RenderRequest request = new RenderRequest(
    filePath, source, format, pageNum,  // pageNum = which page
    zoom, version, true, reason, project
);

// Render respects cache for unchanged pages
RenderResult result = facade.render(request, cached);

// Display requested page
int displayPage = request.getPage();
ImageItem item = result.getImageItem(displayPage);
```

--------------------------------

### PlantUmlPreviewPanel Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/09-preview-panel.md

Initializes the PlantUmlPreviewPanel. Requires the IntelliJ project, parent editor, and a parent UI component for DPI scaling.

```java
public PlantUmlPreviewPanel(Project project, 
                            PlantUmlPreviewEditor fileEditor, 
                            JComponent parent)
```

--------------------------------

### Settings and Configuration

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/00-index.md

Access and manage the PlantUML plugin's configuration via `PlantUmlSettings.getInstance()`. This covers JAR management, Graphviz settings, rendering options, caching, encoding, directives, and editor features.

```APIDOC
## Settings and Configuration

### Description
Complete PlantUML plugin configuration accessible via `PlantUmlSettings.getInstance()`.

### Configuration Categories
- PlantUML JAR management
- Graphviz configuration
- Rendering options (delay, auto-render, auto-hide)
- Caching settings
- Text encoding
- PlantUML directives and include paths
- Preview display options
- Export format defaults
- Editor features (completion, highlighting, pairing)
- Link rendering and navigation
- Remote server rendering
- Persistence and state management

### Persistent Storage
XML serialization in `plantuml.xml`
```

--------------------------------

### Settings Equality and Hashing

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/05-settings-configuration.md

Settings instances support reflection-based equality and hashing. The `equals` method compares all fields, and the `hashCode` method reflects all fields.

```java
boolean equals(Object o)  // Compares all fields
int hashCode()            // Reflects all fields
```

--------------------------------

### Extracting All Diagrams

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/07-source-extraction.md

Extracts all PlantUML diagrams found within a given text. It returns a map of starting positions to their corresponding source code.

```APIDOC
## extractSources

### Description
Extracts all PlantUML diagrams from text.

### Method Signature
`public static Map<Integer, String> extractSources(String text)`

### Parameters
#### Path Parameters
- **text** (String) - Required - The text to extract diagrams from.

### Returns
A LinkedHashMap where:
- **Key:** Position (offset) where diagram starts in text
- **Value:** Full diagram source with @startuml/@enduml tags

### Supports
1. Standard format: `@startuml` ... `@enduml`
2. Markdown format: ` ```plantuml` ... ` ``` `
3. Any variant: `@startmindmap`, `@startjson`, etc.

### Example
```java
String text = document.getText();
Map<Integer, String> diagrams = SourceExtractor.extractSources(text);

for (Map.Entry<Integer, String> entry : diagrams.entrySet()) {
    int position = entry.getKey();
    String source = entry.getValue();
    System.out.println("Diagram at offset " + position);
}
```
```

--------------------------------

### Zoom Management Methods

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/09-preview-panel.md

Provides methods to get and set the current zoom level of the diagram. The display updates automatically when the zoom level changes.

```java
Zoom getZoom()
```

```java
void setZoom(Zoom zoom)
```

--------------------------------

### Prepare PlantUML Environment

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Configures the PlantUML runtime environment before rendering. Must be called before rendering.

```java
public static void prepareEnvironment(Project project, String sourceFilePath)
```

--------------------------------

### Configure HttpClient with Proxy Support

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/10-remote-rendering.md

Builds an HttpClient instance configured to use the IDE's proxy settings. This ensures that remote rendering requests are routed through the appropriate network proxy if one is configured.

```java
HttpClient.newBuilder()
    .proxy(new IdeaWideProxySelector())
    .build()
```

--------------------------------

### Initialize PlantUmlApplicationComponent

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/11-plugin-components.md

Registers global listeners for document, caret, and selection changes when the plugin initializes. These listeners trigger rendering across all open editors.

```java
public void initComponent()
```

--------------------------------

### Render and Save PlantUML to File in Java

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Shows how to render a PlantUML diagram and save it directly to a specified file path. Supports different image formats like SVG.

```java
PlantUmlFacade facade = PlantUmlFacade.get();
String source = "@startuml\nClass A\n@enduml";
Zoom zoom = new Zoom(100, settings);

facade.renderAndSave(
    project,
    source,
    new File("/tmp/diagram.puml"),
    ImageFormat.SVG,
    "/output/diagram.svg",
    "",           // pathPrefix for multi-file
    zoom,
    0             // pageNumber
);
```

--------------------------------

### Extract All Diagrams from Text (Java)

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/07-source-extraction.md

Extracts all PlantUML diagrams from a given text. Supports standard, markdown, and other variants like @startmindmap. Returns a map of starting positions to diagram sources.

```java
public static Map<Integer, String> extractSources(String text)
```

```java
String text = document.getText();
Map<Integer, String> diagrams = SourceExtractor.extractSources(text);

for (Map.Entry<Integer, String> entry : diagrams.entrySet()) {
    int position = entry.getKey();
    String source = entry.getValue();
    System.out.println("Diagram at offset " + position);
}
```

--------------------------------

### Configure HTTP Client for Remote Rendering

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/10-remote-rendering.md

Creates an HTTP client instance configured with specific timeouts, proxy support, and a thread pool for concurrent requests. This is used for communicating with the PlantUML server.

```java
private static HttpClient getHttpClient(PlantUmlSettings plantUmlSettings)
```

--------------------------------

### Normal Rendering Strategy

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Utilizes the standard PlantUML renderer for complete diagrams, supporting multiple pages and incremental caching. Use when partial rendering is not required or enabled.

```java
renderResult = NORMAL_RENDERER.doRender(renderRequest, cachedItem, sourceSplit);
```

--------------------------------

### Check for Missing Image or Zoom Change

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/04-render-cache.md

Combines checks for missing image data and changes in the zoom level. Re-rendering may be necessary if this returns true, for example, due to a zoom change.

```java
boolean imageMissingOrZoomChanged(int page, Zoom zoom)
```

```java
if (cachedItem.imageMissingOrZoomChanged(0, newZoom)) {
    // Need to re-render due to zoom change
}
```

--------------------------------

### State Management Methods

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/05-settings-configuration.md

Provides methods for retrieving the current state and loading a new state for the PlantUML settings.

```java
PlantUmlSettings getState()           // Returns this
void loadState(PlantUmlSettings state) // Copies bean, publishes change notification
```

--------------------------------

### Intelligent PlantUML Cache Usage in Java

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Illustrates how to leverage the caching mechanism to avoid re-rendering diagrams when the source or zoom level hasn't changed. Checks cache validity before re-rendering.

```java
RenderCacheItem cachedItem = ...;  // From previous render

String newSource = "...";
RenderRequest newRequest = ...;

if (cachedItem != null && 
    !cachedItem.sourceChanged(newSource) &&
    !cachedItem.zoomChanged(newRequest) &&
    !cachedItem.imageMissing(-1)) {
    
    // Cache valid, use cached result
    RenderResult result = cachedItem.getRenderResult();
    
} else {
    // Cache invalid or missing, re-render
    RenderResult result = facade.render(newRequest, cachedItem);
    cachedItem = new RenderCacheItem(newRequest, result, 0, version++);
}
```

--------------------------------

### Core API - PlantUmlFacade

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/00-index.md

The PlantUmlFacade provides the primary entry point for rendering and diagram manipulation within the plugin. It supports static access via `PlantUmlFacade.get()` and offers methods for syntax validation, rendering, export, version retrieval, source encoding, and file operations.

```APIDOC
## PlantUmlFacade

### Description
Provides the primary entry point for rendering and diagram manipulation. Supports static access via `PlantUmlFacade.get()`.

### Methods
- Syntax validation
- Rendering and export operations
- Version and metadata retrieval
- Source encoding for server sharing
- File operations (save, extract, filename generation)

### Related Classes
- `FacadeImpl`
- `PlantUmlFacade`
```

--------------------------------

### Check if Export Format Differs from Cached Format

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/04-render-cache.md

Determines if the requested export format differs from the format used in the cached render. For example, a cache hit for PNG at 100% zoom will return true if the new request is for SVG at 100% zoom.

```java
boolean differentFormat(RenderRequest renderRequest)
```

--------------------------------

### Create Zoom Levels for PlantUML Previews

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Instantiate and manage zoom levels for PlantUML diagrams within the IDE. This includes creating standard zoom levels, scaled zoom for high-DPI displays, and unscaled zoom for exports. Use these objects to control diagram scaling.

```java
PlantUmlSettings settings = PlantUmlSettings.getInstance();

// Standard zoom (100%) without system scaling
Zoom zoom100 = new Zoom(100, settings);

// High zoom (200%)
Zoom zoom200 = new Zoom(200, settings);

// Zoom with system DPI scaling (for Retina displays)
JComponent parent = preview.getComponent();
Zoom zoomScaled = new Zoom(parent, 100, settings);
int displayZoom = zoomScaled.getScaledZoom();  // May be 200 on Retina

// Zoom for export (unscaled, actual pixels)
Zoom zoomExport = zoom100.unscaled(settings);
```

--------------------------------

### Singleton Instance Access

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Obtain the singleton instance of the PlantUmlFacade to access its methods. This is the entry point for all facade operations.

```APIDOC
## Static Access

### Method
`get()`

### Signature
`static PlantUmlFacade get()`

### Returns
Singleton instance obtained via `Classloaders.getFacade()`

### Usage Example
```java
PlantUmlFacade facade = PlantUmlFacade.get();
```
```

--------------------------------

### RenderResult Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Initializes a new instance of the RenderResult class.

```APIDOC
## RenderResult Constructor

### Description
Initializes a new instance of the RenderResult class.

### Parameters
- **strategy** (RenderingType) - Required - The rendering strategy used (NORMAL, PARTIAL, or REMOTE).
- **totalPages** (int) - Required - The total number of diagram pages.
```

--------------------------------

### ImageItem Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Constructs an ImageItem representing a single rendered diagram page. It takes various parameters including base directory, image format, document and page source, page index, description, image bytes, rendering type, title, custom filename, and any exception that occurred.

```java
public ImageItem(File baseDir,
                 ImageFormat format,
                 String documentSource,
                 String pageSource,
                 int page,
                 String description,
                 byte[] imageBytes,
                 byte[] svgBytes,
                 RenderingType renderingType,
                 String title,
                 String customFileName,
                 Throwable exception)
```

--------------------------------

### Pagination Control Methods

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/09-preview-panel.md

Allows selection and retrieval of the currently displayed diagram page. Use -1 to indicate all pages.

```java
void setSelectedPage(int page)
```

```java
int getSelectedPage()
```

--------------------------------

### Apply PlantUML Options

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Applies configured PlantUML options such as Graphviz path and size limits.

```java
public static void applyPlantumlOptions(PlantUmlSettings plantUmlSettings)
```

--------------------------------

### Configure and Perform Remote Rendering

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

This snippet shows how to enable remote rendering, set the server prefix, and create a render request to generate an SVG image. It then checks the result for successful rendering.

```java
PlantUmlSettings settings = PlantUmlSettings.getInstance();
settings.setRemoteRendering(true);
settings.setServerPrefix("https://www.plantuml.com/plantuml");

String source = "@startuml\nClass A\n@enduml";
Zoom zoom = new Zoom(100, settings);

RenderRequest request = new RenderRequest(
    "/tmp/diagram.puml",
    source,
    ImageFormat.SVG,
    -1,  // All pages
    zoom,
    null,
    true,
    RenderCommand.Reason.MANUAL_UPDATE,
    project
);

RenderResult result = PlantUmlFacade.get().render(request, null);

for (ImageItem item : result.getImageItems()) {
    if (item.hasImageBytes()) {
        System.out.println("Remote render successful");
    } else {
        System.out.println("Page not rendered: " + item.getDescription());
    }
}
```

--------------------------------

### Manage PlantUML Directory

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Sets or resets the PlantUML working directory and configures include paths.

```java
public static void setPlantUmlDir(File baseDir)
```

```java
public static void resetPlantUmlDir()
```

--------------------------------

### Render Diagram with Facade

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Render a PlantUML diagram using a RenderRequest and an optional cached item. The result contains the rendered images and metadata.

```java
RenderRequest request = new RenderRequest(filePath, source, ImageFormat.PNG, 0, zoom, null, true, reason, project);
RenderResult result = facade.render(request, cachedItem);
List<ImageItem> diagrams = result.getImageItems();
```

--------------------------------

### Access PlantUML Settings Instance

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/05-settings-configuration.md

Retrieve the application-level settings singleton for the PlantUML plugin. This is the standard way to access configuration properties.

```java
PlantUmlSettings settings = PlantUmlSettings.getInstance();
```

--------------------------------

### Rendering and Saving

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Render PlantUML source code to a specified image format and save it to a file. Supports various formats and zoom levels.

```APIDOC
## Rendering and Export

### Method
`renderAndSave`

### Parameters
- `project` (Project) - IntelliJ project context
- `source` (String) - PlantUML source code
- `sourceFile` (File) - File containing the source
- `format` (ImageFormat) - Export format (PNG, SVG, UTXT, ATXT, EPS, TEX, TIKZ)
- `path` (String) - Destination file path
- `pathPrefix` (String) - Prefix for multi-page exports
- `zoom` (Zoom) - Zoom level settings (see Zoom class)
- `pageNumber` (int) - Which diagram page to export (0-indexed)

### Returns
`void`

### Throws
`IOException` - if file writing fails or remote rendering is enabled (throws RuntimeException)

### Example
```java
Zoom zoom = new Zoom(100, settings); // 100% zoom
facade.renderAndSave(project, source, sourceFile, ImageFormat.PNG, "/tmp/diagram.png", "", zoom, 0);
```
```

--------------------------------

### Rendering API

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/00-index.md

Provides methods to render PlantUML diagrams. It allows obtaining a facade instance and performing rendering operations with specified requests and cached items.

```APIDOC
## Rendering API

### Description
Provides methods to render PlantUML diagrams. It allows obtaining a facade instance and performing rendering operations with specified requests and cached items.

### Methods

#### `PlantUmlFacade.get()`

*   **Description:** Retrieves the singleton instance of the `PlantUmlFacade`.
*   **Returns:** An instance of `PlantUmlFacade`.

#### `facade.render(renderRequest, cachedItem)`

*   **Description:** Renders a PlantUML diagram. This method takes a `renderRequest` object and a `cachedItem` as input.
*   **Parameters:**
    *   `renderRequest` (Object) - The request object containing rendering details.
    *   `cachedItem` (Object) - The cached item to potentially use or update.
*   **Returns:** A `RenderResult` object containing the rendering output.
```

--------------------------------

### Iterating and Rendering Multiple PlantUML Diagrams

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/07-source-extraction.md

Shows how to iterate through a map of extracted PlantUML sources and render each one, typically for creating separate pages or tabs in a multi-diagram view.

```java
// Or render all with pagination
int pageNum = 0;
for (String source : sources.values()) {
    // Render each as separate page
}
```

--------------------------------

### Create DiagramFactory

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Creates a DiagramFactory instance from a SourceStringReader and Project. Useful for obtaining diagram-related information like filename and page count.

```java
public static DiagramFactory create(SourceStringReader reader, Project project)
```

```java
SourceStringReader reader = new SourceStringReader(source);
DiagramFactory factory = DiagramFactory.create(reader, project);
String filename = factory.getFilename(0);
int pages = factory.getPageCount();
```

--------------------------------

### Render and Save Diagram to File

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Renders a PlantUML diagram and saves the output to one or more files. Useful for exporting diagrams to disk.

```java
public static void renderAndSave(RenderRequest renderRequest, String path, String pathPrefix)
        throws IOException
```

--------------------------------

### Rendering and Saving

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Renders a PlantUML diagram and saves the output to one or more files. It prepares the rendering environment and delegates the actual export process to PlantUmlExporter.

```APIDOC
## renderAndSave

### Description
Renders diagram and saves to file(s).

### Method
```java
public static void renderAndSave(RenderRequest renderRequest, String path, String pathPrefix) throws IOException
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **renderRequest** (RenderRequest) - Required - Render parameters
- **path** (String) - Required - Destination file path
- **pathPrefix** (String) - Required - Prefix for multi-file exports (e.g., "diagram" → "diagram_0.png", "diagram_1.png")

### Throws
- `IOException` if file write fails

### Process
1. Prepares environment
2. Delegates to PlantUmlExporter
3. Writes image bytes to disk
```

--------------------------------

### Partial Rendering Strategy

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Employs partial rendering for faster incremental updates on single-page diagrams when the `!idea_partial_render` directive is present. Note that this strategy has limitations regarding @newpage directives and includes.

```java
if (partialRender) {
    renderResult = new PlantUmlPartialRenderer().partialRender(
        renderRequest, cachedItem, sourceSplit);
}
```

--------------------------------

### Rendering

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Render PlantUML source code to an image, returning a `RenderResult` object. This method can utilize cached items for efficiency.

```APIDOC
## Rendering

### Method
`render`

### Parameters
- `renderRequest` (RenderRequest) - Request object containing source, format, page, zoom, and project
- `cachedItem` (RenderCacheItem) - Previously cached render result (null if no cache)

### Returns
`RenderResult` - containing rendered diagrams and metadata

### Example
```java
RenderRequest request = new RenderRequest(filePath, source, ImageFormat.PNG, 0, zoom, null, true, reason, project);
RenderResult result = facade.render(request, cachedItem);
List<ImageItem> diagrams = result.getImageItems();
```
```

--------------------------------

### RenderResult Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Initializes a new RenderResult object with the specified rendering strategy and total number of pages.

```java
public RenderResult(RenderingType strategy, int totalPages)
```

--------------------------------

### Zoom Constructors

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/09-preview-panel.md

Provides constructors for creating Zoom objects, with and without system scaling.

```java
// With system scaling
Zoom(JComponent context, int unscaledZoom, PlantUmlSettings settings)

// Without system scaling
Zoom(int unscaledZoom, PlantUmlSettings settings)
```

--------------------------------

### Version Checking Method

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/05-settings-configuration.md

Handles auto-upgrade logic when the bundled PlantUML version is updated.

```java
void checkVersion(String bundledVersion)
```

--------------------------------

### RenderRequest Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Use this constructor to create a new rendering request. It takes all necessary parameters for a PlantUML diagram rendering operation.

```java
public RenderRequest(String sourceFilePath,
                     String source,
                     ImageFormat format,
                     int page,
                     Zoom zoom,
                     Integer version,
                     boolean renderUrlLinks,
                     RenderCommand.Reason reason,
                     Project project)
```

--------------------------------

### Render and Save PlantUML Diagram

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Render a PlantUML diagram and save it to a specified file path in a given format. This method handles file writing and supports various image formats.

```java
Zoom zoom = new Zoom(100, settings); // 100% zoom
facade.renderAndSave(project, source, sourceFile, ImageFormat.PNG, 
                     "/tmp/diagram.png", "", zoom, 0);
```

--------------------------------

### Creating a Render Request with Extracted Source

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/07-source-extraction.md

Constructs a RenderRequest object containing the extracted PlantUML source, file path, and rendering options for previewing. This is used in the preview panel workflow.

```java
PlantUmlPreviewPanel panel = ...;
RenderRequest request = new RenderRequest(
    filePath, 
    SourceExtractor.extractSource(document, caretOffset),
    format,
    0,
    zoom,
    version,
    true,
    reason,
    project
);
RenderResult result = PlantUmlFacade.get().render(request, cachedItem);
```

--------------------------------

### Display Diagram in PlantUML Preview Panel

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

This code shows how to extract PlantUML source from a document and trigger rendering and display within the `PlantUmlPreviewPanel`. The panel handles the rendering process internally.

```java
PlantUmlPreviewPanel panel = ...;

String source = SourceExtractor.extractSource(document, caretOffset);
if (!source.isEmpty()) {
    Zoom zoom = panel.getZoom();
    
    RenderRequest request = new RenderRequest(
        filePath, source, ImageFormat.PNG, 0, zoom, version, true,
        RenderCommand.Reason.CARET, project
    );
    
    // Panel handles rendering and display internally
    // Just requesting will trigger render via LazyApplicationPoolExecutor
}
```

--------------------------------

### Save Diagram to File

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Saves a generated diagram image to a specified file path. Ensure the PlantUML facade is initialized.

```java
RenderResult result = ...;
ImageItem item = result.getImageItem(0);

String outputPath = "/tmp/diagram.png";
facade.save(outputPath, item.getImageBytes());
System.out.println("Saved to: " + outputPath);
```

--------------------------------

### Version Information

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/02-core-api-facade.md

Retrieve the version string of the PlantUML engine being used.

```APIDOC
## Version Information

### Method
`version()`

### Returns
`String` - PlantUML version string
```

--------------------------------

### RenderCacheItem Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/04-render-cache.md

Initializes a new RenderCacheItem with the provided render request, result, page number, and cache version. Use this to create a cache entry for a specific rendering.

```java
public RenderCacheItem(RenderRequest renderRequest, 
                       RenderResult renderResult, 
                       int requestedPage, 
                       int version)
```

--------------------------------

### General Error Handling Pattern

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/12-error-handling.md

Implement a try-catch block to handle specific exceptions and unexpected throwables. Always log errors with context, clean up resources, return a sensible error state, and inform the user.

```java
try {
    // Operation code
} catch (SpecificException e) {
    LOG.error("Operation failed: description", e);
    // Handle: throw, return error state, or retry
} catch (Throwable e) {
    LOG.error("Unexpected error", e);
    // Generic handler
}
```

--------------------------------

### Extracting PlantUML Source at Cursor for Pagination

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/07-source-extraction.md

Demonstrates extracting a specific PlantUML source block at the cursor position, which can be used for rendering individual diagrams when pagination is enabled for multi-diagram files.

```java
// Extract at cursor position
String caretSource = SourceExtractor.extractSource(document, caretOffset);
```

--------------------------------

### RenderResult Query Methods

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Methods for retrieving rendered diagrams and general information about the rendering operation.

```APIDOC
## RenderResult Query Methods

### Description
Methods for retrieving rendered diagrams and general information about the rendering operation.

### Methods
- **getImageItems()** (List<ImageItem>) - Returns a list of all rendered diagrams.
- **getImageItem(int i)** (ImageItem) - Returns a specific diagram by its index.
- **getImageItemsAsArray()** (ImageItem[]) - Returns the diagrams as an array.
- **getPages()** (int) - Returns the total page count of the diagrams.
- **getStrategy()** (RenderingType) - Returns the rendering strategy used.
- **hasError()** (boolean) - Returns true if any diagram has an error, false otherwise.
- **getFirstDiagramBytes()** (byte[]) - Returns the image bytes of the first non-title diagram.
```

--------------------------------

### State Persistence Method

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/09-preview-panel.md

Sets a component to persist the selected page across editor sessions. This ensures the user's last viewed page is restored.

```java
void setSelectedPagePersistentStateComponent(SelectedPagePersistentStateComponent component)
```

--------------------------------

### RenderRequest Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Constructs a RenderRequest object with all necessary parameters for a rendering operation.

```APIDOC
## RenderRequest Constructor

### Description
Container for all parameters needed to render a PlantUML diagram. Represents a single rendering operation request.

### Method Signature
```java
public RenderRequest(String sourceFilePath, String source, ImageFormat format, int page, Zoom zoom, Integer version, boolean renderUrlLinks, RenderCommand.Reason reason, Project project)
```

### Parameters
#### Path Parameters
- **sourceFilePath** (String) - Required - Absolute path to the PlantUML source file
- **source** (String) - Required - PlantUML source code including @startuml/@enduml tags
- **format** (ImageFormat) - Required - Export format: PNG, SVG, UTXT, ATXT, EPS, TEX, TIKZ
- **page** (int) - Required - Page/diagram index (0-based), or -1 for all pages
- **zoom** (Zoom) - Required - Zoom level and scaling information
- **version** (Integer) - Optional - Version identifier for cache invalidation
- **renderUrlLinks** (boolean) - Required - Whether to render clickable hyperlinks in SVG
- **reason** (RenderCommand.Reason) - Optional - Why rendering was triggered (CARET, FILE_SWITCHED, REFRESH, etc.)
- **project** (Project) - Required - IntelliJ project context
```

--------------------------------

### Access PlantUML Settings

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/00-index.md

Retrieve the PlantUML plugin settings instance. Use this to access configuration values like the Graphviz executable path.

```java
PlantUmlSettings settings = PlantUmlSettings.getInstance();
String dotPath = settings.getDotExecutable();
```

--------------------------------

### Handling PartialRenderingException

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/12-error-handling.md

Demonstrates how to catch PartialRenderingException during partial rendering, allowing a fallback to normal rendering or error display.

```java
try {
    renderResult = new PlantUmlPartialRenderer()
        .partialRender(renderRequest, cachedItem, sourceSplit);
} catch (PartialRenderingException e) {
    // Fall back to normal rendering or display error
}
```

--------------------------------

### RenderResult State Query Methods

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Methods for querying the state of the RenderResult, such as checking for the presence of a file in the included files list.

```APIDOC
## RenderResult State Query Methods

### Description
Methods for querying the state of the RenderResult, such as checking for the presence of a file in the included files list.

### Methods
- **includedFilesContains**(File) - (boolean) - Checks if a given file is present in the list of included files.
```

--------------------------------

### Handle and Render Multiple PlantUML Diagrams

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/13-usage-examples.md

Extract all PlantUML diagrams from a document and render each one individually. This allows for processing multiple diagrams within a single file.

```java
String documentText = document.getText();
Map<Integer, String> diagrams = SourceExtractor.extractSources(documentText);

System.out.println("Found " + diagrams.size() + " diagrams");

int pageNum = 0;
for (Map.Entry<Integer, String> entry : diagrams.entrySet()) {
    int offset = entry.getKey();
    String source = entry.getValue();
    
    // Render each diagram
    RenderRequest request = new RenderRequest(
        filePath, source, ImageFormat.PNG, 0, zoom, null, true, reason, project
    );
    RenderResult result = PlantUmlFacade.get().render(request, null);
    
    System.out.println("Diagram " + pageNum + " at offset " + offset);
    pageNum++;
}
```

--------------------------------

### Creating SourceStringReader

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Creates a configured PlantUML SourceStringReader instance, which is essential for processing PlantUML source code before rendering. It sets up encoding, PlantUML directives, and file-based defines.

```APIDOC
## newSourceStringReader

### Description
Creates PlantUML's SourceStringReader with proper configuration.

### Method
```java
public static SourceStringReader newSourceStringReader(String source, RenderRequest renderRequest)
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **source** (String) - Required - PlantUML source code
- **renderRequest** (RenderRequest) - Required - Request with test flag and settings

### Returns
- **SourceStringReader** - Configured SourceStringReader for rendering

### Configuration
- **Encoding:** From PlantUmlSettings (default UTF-8)
- **Config:** PlantUML directives from settings
- **Defines:** File-based defines for preprocessor

### Example
```java
SourceStringReader reader = PlantUmlRendererUtil.newSourceStringReader(
    source, renderRequest);
Diagram diagram = reader.getPlantUmlDiagram();
```
```

--------------------------------

### Handling IncompatiblePlantUmlVersionException

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/12-error-handling.md

Shows how a ClassNotFoundException during PlantUML class loading is caught and re-thrown as an IncompatiblePlantUmlVersionException.

```java
try {
    // Load PlantUML classes
} catch (ClassNotFoundException e) {
    throw new IncompatiblePlantUmlVersionException(
        "PlantUML version incompatible", e);
}
```

--------------------------------

### Extract PlantUML from Dot File

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/07-source-extraction.md

Renders Graphviz DOT files directly by wrapping their content with @startuml/@enduml tags, allowing them to be processed as PlantUML diagrams.

```dot
digraph G {
    A -> B;
}
```

```plantuml
@startuml
digraph G {
    A -> B;
}
@enduml
```

--------------------------------

### Create PlantUML SourceStringReader

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/08-rendering-utilities.md

Creates a configured PlantUML SourceStringReader for rendering. This method handles setting up encoding, directives, and defines based on IDE settings.

```java
SourceStringReader reader = PlantUmlRendererUtil.newSourceStringReader(
    source, renderRequest);
Diagram diagram = reader.getPlantUmlDiagram();
```

--------------------------------

### RenderRequest Copy Constructor

Source: https://github.com/esteinberg/plantuml4idea/blob/master/_autodocs/03-render-request-result.md

Creates a new RenderRequest based on an existing one, allowing modification of the image format.

```APIDOC
## RenderRequest Copy Constructor

### Description
Creates a new request based on existing request but with different format.

### Method Signature
```java
public RenderRequest(RenderRequest original, ImageFormat format)
```

### Parameters
#### Path Parameters
- **original** (RenderRequest) - Required - The original RenderRequest to copy from.
- **format** (ImageFormat) - Required - The new export format for the copied request.
```