### Hyprlauncher CLI Examples

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/README.md

Demonstrates various ways to use the Hyprlauncher command-line interface, including starting as a daemon, opening with specific options, and reading from stdin.

```bash
# Start daemon
hyprlauncher -d
```

```bash
# Open launcher (or toggle if running)
hyprlauncher
```

```bash
# Open with options
hyprlauncher -o "firefox,chrome,safari"
```

```bash
# Read options from pipe (dmenu-compatible)
echo -e "option1\noption2" | hyprlauncher -m
```

```bash
# Toggle state
hyprlauncher -t
```

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

### Complete Hyprlauncher Client Integration Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/ipc-protocol.md

This C++ example demonstrates a full client-to-daemon integration with Hyprlauncher. It covers connecting to the daemon, setting up protocol implementations, handling handshakes, binding protocols, and interacting with protocol objects like 'Info'. Callbacks for state changes and selection events are also set up.

```cpp
// Connect to daemon
auto socket = Hyprwire::IClientSocket::open("/run/user/1000/.hyprlauncher.sock");

// Create implementation
auto coreImpl = makeShared<CCHyprlauncherCoreImpl>(1);
socket->addImplementation(coreImpl);
socket->waitForHandshake();

// Bind protocol and get manager
auto manager = makeShared<CCHyprlauncherCoreManagerObject>(
    socket->bindProtocol(coreImpl->protocol(), 1)
);

// Get info object
auto info = makeShared<CCHyprlauncherCoreInfoObject>(
    manager->sendGetInfoObject()
);

// Set up callbacks
info->setOpenState([](uint32_t state) {
    std::cout << "Open state: " << state << std::endl;
});

info->setSelectionMade([](const char* sel) {
    std::cout << sel << std::endl;  // Print result
});

// Send command
manager->sendSetOpenState(1);  // Open launcher

// Wait for events
while (socket->dispatchEvents(true)) {
    // Process events
}
```

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

### CUI windowOpen() Method Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Example of checking the current visibility state of the launcher window using the windowOpen() method.

```cpp
if (g_ui->windowOpen()) {
    // Window is visible
}
```

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

### Example .desktop File Structure

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

This is an example of a standard FreeDesktop .desktop file. It includes essential fields like Name, Exec, and Type, along with optional fields such as Description, Icon, and Categories.

```ini
[Desktop Entry]
Version=1.0
Type=Application
Name=Mozilla Firefox
GenericName=Web Browser
Comment=Browse the web
Icon=firefox
Exec=firefox %U
Categories=Network;WebBrowser;
Keywords=web;browser;internet;
Terminal=false

```

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

### Example Implementation of init

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinder.md

Shows how to override the `init` method in a subclass to initialize a cache and set up file watchers.

```cpp
class CMyFinder : public IFinder {
    void init() override {
        // Initialize cache
        m_cache = makeUnique<CEntryCache>("my_finder");
        // Setup file watchers
        m_inotifyFd = inotify_init();
    }
};
```

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

### CUI setWindowOpen() Method Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Examples demonstrating how to open or close the launcher window using setWindowOpen. This method synchronizes UI state and notifies IPC clients.

```cpp
// From keyboard handler
if (e.xkbKeysym == XKB_KEY_Escape) {
    g_ui->setWindowOpen(false);
}

// From IPC command
if (command == "open") {
    g_ui->setWindowOpen(true);
}
```

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

### CUI Constructor Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Example of how to instantiate and run the CUI class. The constructor initializes UI elements, and run() enters the event loop.

```cpp
// In main()
g_ui = makeUnique<CUI>(openByDefault);
g_ui->run();  // Enter event loop
```

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

### CUI run() Method Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Example of initializing the CUI and entering its main event loop. This call blocks until the application exits.

```cpp
g_ui = makeUnique<CUI>(true);  // open by default
g_ui->run();  // Block in event loop until exit
```

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

### System Locale Detection Examples

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/i18n.md

Demonstrates how the system locale is detected based on environment variables like LANG, with examples for German, Japanese, and English.

```bash
# German
LANG=de_DE.UTF-8  →  Uses "de_DE" translations

# Japanese
LANG=ja_JP.UTF-8  →  Uses "ja_JP" translations

# English (default)
LANG=en_US.UTF-8  →  Uses "en_US" translations
```

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

### Example Hyprlauncher Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

This is a sample configuration file for Hyprlauncher, demonstrating various settings for general options, locale, cache, finders, and UI.

```ini
general {
    grab_focus = 1
}

locale {
    override = en_US
}

cache {
    enabled = 1
}

finders {
    default_finder = desktop
    
    desktop_prefix = 
    unicode_prefix = .
    math_prefix = =
    font_prefix = '
    
    desktop_launch_prefix = 
    desktop_terminal = kitty -e
    desktop_icons = 1
}

ui {
    window_size = 400 260
}
```

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

### Desktop Launch Configuration Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Configuration settings for launching desktop applications, specifying a D-Bus launch prefix and a terminal command.

```ini
finders {
    desktop_launch_prefix = dbus-launch
    desktop_terminal = kitty -e
}
```

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

### I18n Localize Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/types.md

Example of how to use I18n::localize to get placeholder text for the search box.

```cpp
auto placeholder = I18n::localize(I18n::TXT_KEY_SEARCH_SOMETHING, {});
m_inputBox->placeholder(placeholder);
```

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

### Building Hyprlauncher with Nix

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/README.md

Build instructions for Hyprlauncher using Nix, including flake updates and development environment setup.

```bash
nix flake update
nix develop
make all
```

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

### init

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinder.md

An optional initialization method called when the finder is first created. Override this method to perform one-time setup tasks.

```APIDOC
## init

### Description
Optional initialization method called when the finder is first created. Override this method to perform one-time setup such as loading cache files, scanning directories, or setting up file watchers.

### Method
`virtual void init();`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
None

### Request Example
```cpp
class CMyFinder : public IFinder {
    void init() override {
        // Initialize cache
        m_cache = makeUnique<CEntryCache>("my_finder");
        // Setup file watchers
        m_inotifyFd = inotify_init();
    }
};
```

### Response
#### Success Response
- **Return Type:** `void`

### Response Example
None (void return type)
```

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

### Initialize and Parse Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Example of initializing the global CConfigManager instance and parsing the configuration file upon application startup.

```cpp
// In main()
g_configManager = makeUnique<CConfigManager>();
g_configManager->parse();
```

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

### Example of Executing a Terminal Application Launch

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Demonstrates the constructed command for launching a terminal application, including the prefix, terminal emulator, and application executable.

```bash
/bin/sh -c "dbus-launch kitty -e /usr/bin/app"
```

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

### Example: Sending Window Open State

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Shows how to call sendOpenState to notify clients when the window has just opened.

```cpp
// In CUI::setWindowOpen()
g_serverIPCSocket->sendOpenState(true);  // Window just opened
```

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

### Example Usage of SFinderResult

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/types.md

Shows how to iterate through search results, access their properties like label and icon, and execute the associated action.

```cpp
std::vector<SFinderResult> results = finder->getResultsForQuery("firefox");

for (const auto& r : results) {
    std::cout << "Label: " << r.label << std::endl;
    std::cout << "Icon: " << r.icon << std::endl;
    std::cout << "Has icon: " << r.hasIcon << std::endl;
    
    // Execute the result when selected
    r.result->run();
}
```

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

### Example Usage of getResultsForQuery

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinder.md

Demonstrates how to obtain a finder instance and retrieve search results for a query, then iterate through the results to display their labels and icons.

```cpp
auto finder = g_desktopFinder;  // Get a finder instance
std::vector<SFinderResult> results = finder->getResultsForQuery("firefox");

for (const auto& result : results) {
    std::cout << "Label: " << result.label << std::endl;
    std::cout << "Icon: " << result.icon << std::endl;
}
```

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

### init Method Signature

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinder.md

An optional initialization method that can be overridden by subclasses to perform one-time setup tasks when the finder is created.

```cpp
virtual void init();
```

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

### Example: Executing IFinderResult::run()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinderresult.md

Shows how to execute the primary action associated with a search result by calling its `run()` method. This is typically done when a user selects a result.

```cpp
std::vector<SFinderResult> results = finder->getResultsForQuery("calc");
if (!results.empty()) {
    results[0].result->run();  // Execute the selected result
}
```

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

### CQueryProcessor Constructor

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/queryprocessor.md

Initializes and starts the background query processing thread. This is called once during application startup.

```APIDOC
## CQueryProcessor()

### Description
Creates and starts the background query processing thread. The thread waits on a condition variable until a query is scheduled. Called once during application initialization in `main()`.

### Example Usage:
```cpp
// Called automatically once
g_queryProcessor = makeUnique<CQueryProcessor>();
```
```

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

### Manually Reload Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Example of manually calling the parse method to reload the configuration file at any time.

```cpp
g_configManager->parse();
```

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

### CEntryCache Constructor Example

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/entrycache.md

Demonstrates how to initialize a CEntryCache instance for a specific finder, such as the desktop finder. The constructor handles loading frequency data from disk.

```cpp
class CDesktopFinder : public IFinder {
    UP<CEntryCache> m_entryFrequencyCache;
    
public:
    CDesktopFinder() {
        m_entryFrequencyCache = makeUnique<CEntryCache>("desktop");
    }
};

```

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

### Example Usage of eFinderTypes

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/types.md

Demonstrates how to check the type of a finder result to identify if it's an application.

```cpp
auto result = finder->getResultsForQuery("test")[0].result;
if (result->type() == FINDER_DESKTOP) {
    // This is an application
    CDesktopEntry* app = static_cast<CDesktopEntry*>(result.get());
}
```

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

### Example: Using IFinderResult::type()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinderresult.md

Demonstrates how to use the `type()` method to determine the category of a search result and perform actions based on its type.

```cpp
auto result = finder->getResultsForQuery("test")[0].result;
switch (result->type()) {
    case FINDER_DESKTOP:
        std::cout << "This is an application" << std::endl;
        break;
    case FINDER_UNICODE:
        std::cout << "This is a Unicode character" << std::endl;
        break;
}
```

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

### Example: Sending User Selection

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Demonstrates calling sendSelectionMade with the selected entry name when the user presses Enter on a result.

```cpp
// In CUI::onSelected()
g_serverIPCSocket->sendSelectionMade(selectedName);
```

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

### Get Launcher Info Object and Set Callbacks

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/ipc-protocol.md

Requests an info object from the server to receive state change notifications. Callbacks can be set for open state changes.

```cpp
auto infoObj = manager->getInfoObject();
infoObj->setOpenState([](uint32_t state) {
    if (state) std::cout << "Launcher opened\n";
    else std::cout << "Launcher closed\n";
});
```

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

### CServerIPCSocket Constructor

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Starts the IPC server socket, accepting incoming connections from clients. It initializes the socket path, removes stale files, opens the server socket, and registers callbacks for client commands.

```APIDOC
## CServerIPCSocket()

### Description
Starts the IPC server socket, accepting incoming connections from clients.

### Initialization:
1. Reads `$XDG_RUNTIME_DIR` environment variable
2. Constructs socket path: `{XDG_RUNTIME_DIR}/.hyprlauncher.sock`
3. Removes any stale socket file
4. Opens server socket via `Hyprwire::IServerSocket::open()`
5. Creates protocol implementation with object factory callback
6. Adds implementation to socket
7. Registers callbacks for client commands

### Server Callbacks:
- `setSetOpenState`: Called when client sends open/close/toggle command
- `setOpenWithOptions`: Called when client sends options
- `setGetInfoObject`: Called when client requests info object

### Example Usage:
```cpp
// In main()
g_serverIPCSocket = makeUnique<CServerIPCSocket>();

// Later, in event loop, extract FD for polling
m_backend->addFd(g_serverIPCSocket->m_socket->extractLoopFD(), [] {
    g_serverIPCSocket->m_socket->dispatchEvents(false);
});
```
```

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

### Example: Getting IFinderResult::name()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinderresult.md

Demonstrates how to obtain the canonical name or identifier of a search result using the `name()` method. This is used for display and identification purposes.

```cpp
auto result = finder->getResultsForQuery("app")[0].result;
std::string selected = result->name();
std::cout << "Selected: " << selected << std::endl;
```

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

### Example: Retrieving IFinderResult::frequency()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinderresult.md

Shows how to get the usage frequency score of a result using the `frequency()` method. This score is used by the fuzzy matcher to prioritize frequently used items.

```cpp
auto result = finder->getResultsForQuery("firefox")[0].result;
uint32_t timesUsed = result->frequency();
std::cout << "Used " << timesUsed << " times" << std::endl;
```

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

### Hyprlauncher Initialization (main function)

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

The main function handles argument parsing, client connection attempts, and daemonization if not connected as a client. It sets up the server socket, finders, configuration, UI, and event loop.

```cpp
int main(int argc, char** argv, char** envp) {
    // 1. Parse args
    // 2. Try connect as client
    // 3. If connected, send command and exit
    // 4. Otherwise, become daemon:
    //    - Create server socket
    //    - Create all finders
    //    - Initialize config
    //    - Create UI
    // 5. Run event loop
    return 0;
}
```

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

### Initialize and Use DesktopFinder

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Demonstrates how to initialize the CDesktopFinder and retrieve search results for a given query. Shows how to launch a selected application.

```cpp
// Initialize
g_desktopFinder = makeUnique<CDesktopFinder>();
g_desktopFinder->init();

// Later, in query processor
auto results = g_desktopFinder->getResultsForQuery("fire");

for (const auto& r : results) {
    std::cout << r.label << " (" << r.icon << ")" << std::endl;
    // Output:
    // Firefox (firefox)
    // Thunderbird (thunderbird)
}

// User selects and launches
results[0].result->run();  // Launches Firefox
```

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

### Initialize and Use CServerIPCSocket

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Demonstrates how to initialize the global CServerIPCSocket instance in main() and how to add its file descriptor to an event loop for dispatching events.

```cpp
// In main()
g_serverIPCSocket = makeUnique<CServerIPCSocket>();

// Later, in event loop, extract FD for polling
m_backend->addFd(g_serverIPCSocket->m_socket->extractLoopFD(), [] {
    g_serverIPCSocket->m_socket->dispatchEvents(false);
});
```

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

### CDesktopFinder::init

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Initializes the desktop finder by loading all desktop entry files and setting up file watching. This method should be called once during application startup.

```APIDOC
## init

Loads all desktop entry files and sets up file watching.

```cpp
virtual void init();
```

### Description

Called during application startup. Performs:

1. Scans standard .desktop entry directories:
   - `$XDG_DATA_HOME/applications/`
   - `~/.local/share/applications/`
   - `/usr/share/applications/`
   - `/usr/local/share/applications/`
   - Other `$XDG_DATA_DIRS` paths

2. Loads all `.desktop` files using `cacheEntry()`

3. Creates frequency cache from disk

4. Sets up inotify watchers on all directories

5. Registers file descriptor with UI event loop

**Called:** Once during `main()` before UI starts

**Example Usage:**

```cpp
g_desktopFinder = makeUnique<CDesktopFinder>();
g_desktopFinder->init();
```
```

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

### Fuzzy Namespace - Get Results

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Retrieves a specified number of results from an input vector based on a query.

```cpp
std::vector<SP<IFinderResult>> getNResults(
    const std::vector<SP<IFinderResult>>& in,
    const std::string& query,
    size_t results
);
```

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

### Open Launcher with Options

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/ipc-protocol.md

Opens the launcher with a predefined list of options. This replaces normal finder routing and is useful for programmatic control or dmenu mode.

```cpp
std::vector<const char*> opts = {"firefox", "chrome", "safari"};
manager->sendOpenWithOptions(opts);  // Open with explicit choices
```

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

### Hyprlauncher First Launch Flow

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Illustrates the sequence of events when Hyprlauncher is launched for the first time, including client and server socket creation.

```bash
user$ hyprlauncher
  → main() creates client socket
  → Client socket fails to connect (no daemon)
  → main() creates server socket
  → main() creates UI
  → UI enters event loop
  → Ready for connections
```

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

### Client Opens Launcher with Options

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/ipc-protocol.md

Describes the IPC sequence for opening Hyprlauncher with specific options provided by the client. This involves setting up callbacks and then opening the UI with the given choices.

```text
Client                          Daemon
  │                               │
  ├─ open_with_options([...]) ──->│
  │                               │
  ├─ get_info_object() ──────────>│
  │                               │
  │<────── info_object ────────────┤
  │                               │
  │ set_open_state callback        │
  │ set_selection_made callback    │
  │                               │
  │<──────── open_state(1) ────────┤
  │                               │
  │  (UI shows provided options)   │
  │                               │
  │  (user selects option)         │
  │                               │
  │<──── selection_made("option") ─┤
  │                               │
  │ (print selection, exit)        │
  └──────────────────────────────>│
```

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

### Main Entry Point

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

The main function for the Hyprlauncher executable, accepting command-line arguments.

```cpp
int main(int argc, char** argv, char** envp);
```

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

### Registering onInotifyEvent Callback

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Example of registering the onInotifyEvent method as a callback for inotify file descriptor events within the main event loop.

```cpp
m_backend->addFd(g_configManager->m_inotifyFd.get(), 
                 [] { g_configManager->onInotifyEvent(); });
```

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

### Documentation Content Details

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Details the content provided for each API reference file, including method signatures, parameter tables, and usage examples.

```APIDOC
## Documentation Content Details

### Description
This section describes the comprehensive information included within each API reference file.

### API Reference File Content

Each API reference file includes:
  - Class definition and header
  - Overview of purpose
  - Source file locations with line references
  - Public method signatures (full with parameter types)
  - Parameter tables (name | type | required | default | description)
  - Return type documentation
  - Detailed behavior descriptions
  - Code usage examples
  - Integration points with other components
  - Thread safety notes
  - Performance characteristics
  - Configuration references
  - Related types cross-references

### Architecture Documentation

Architecture documentation covers:
  - Data flow diagrams
  - Query routing logic
  - IPC protocol flows
  - Threading model
  - Memory management patterns
  - Module interactions
  - Build configuration
  - Environment variables
```

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

### IFinderResult run() Implementation

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Launches the application represented by the CDesktopEntry. It constructs the command using configuration prefixes and handles desktop-specific format codes before execution.

```cpp
virtual void run();
```

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

### Initialize and Localize Text in C++

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/i18n.md

Demonstrates the workflow for initializing the i18n engine and retrieving localized text for UI elements. This includes setting a placeholder for an input box and notes on how users can override the locale in configuration.

```cpp
// 1. Initialize
I18n::initEngine();

// 2. Get localized text
auto placeholder = I18n::localize(I18n::TXT_KEY_SEARCH_SOMETHING, {});

// 3. Use in UI
m_inputBox->placeholder(placeholder);

// User can override in config:
// locale { override = ja_JP }
// → Placeholder text changes to Japanese
```

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

### sendOpenWithOptions Method for CClientIPCSocket

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Opens the launcher with custom user-provided options and blocks until the user makes a selection or closes the window. The selected item is printed to stdout, and the client process exits.

```cpp
void sendOpenWithOptions(const std::vector<std::string>& opts);
```

```cpp
// Command line: hyprlauncher -o "firefox,chrome,safari"
std::vector<std::string> opts = {"firefox", "chrome", "safari"};
socket->sendOpenWithOptions(opts);
// Blocks until user selects or closes
// Then exits
```

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

### Hyprlauncher Command-Line Usage

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ipcfinder.md

Demonstrates how to use Hyprlauncher with explicit command-line options and how it integrates with scripts.

```APIDOC
## Hyprlauncher Command-Line Options

### Description
Allows users to specify options directly via the command line, which are then presented by Hyprlauncher.

### Usage
```bash
# Open launcher with three choices
hyprlauncher -o "firefox,chrome,safari"

# User selects "chrome"
# Script receives: chrome
```

### Implementation Example
```cpp
// In main()
std::vector<std::string> explicitOptions = {"firefox", "chrome", "safari"};
g_ipcFinder->setData(explicitOptions);
g_queryProcessor->overrideQueryProvider(g_ipcFinder);
g_ui->setWindowOpen(true);
```
```

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

### Hyprlauncher Command-Line Options

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ipcfinder.md

Launches Hyprlauncher with explicitly provided options via the -o flag. The selected option is then printed to stdout.

```bash
# Open launcher with three choices
hyprlauncher -o "firefox,chrome,safari"

# User selects "chrome"
# Script receives: chrome
```

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

### Example: Accessing IFinderResult::fuzzables()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinderresult.md

Illustrates how to retrieve the searchable text fields for a result using the `fuzzables()` method. These fields are used by the fuzzy matcher for ranking.

```cpp
auto result = finder->getResultsForQuery("web")[0].result;
const auto& fuzzables = result->fuzzables();
// May return: ["Firefox", "Mozilla Firefox", "Web Browser", "internet"]
```

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

### Initialize EntryCache for DesktopFinder

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/entrycache.md

Creates a new EntryCache instance for the DesktopFinder, identified by the string "desktop".

```cpp
// DesktopFinder
m_entryFrequencyCache = makeUnique<CEntryCache>("desktop");
```

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

### sendOpenWithOptions

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Opens the launcher with custom user-provided options and blocks until a selection is made or the window is closed.

```APIDOC
## sendOpenWithOptions(const std::vector<std::string>& opts)

### Description
Opens the launcher in daemon mode with explicit options provided by the user. This function blocks until the user makes a selection or closes the window. It then prints the result to stdout or an exit message and exits the client process.

### Parameters:
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters:
- **opts** (`const std::vector<std::string>&`) - Required - Option strings to display in launcher

### Return Type:
`void`

### Flow:
1. Client gets info object from manager
2. Sets up callbacks for `openState` and `selectionMade` events
3. Enters dispatch loop, blocking until user makes selection
4. On selection, prints result and exits
5. On close without selection, prints "Exited without selection"

### Example Usage:
```cpp
// Command line: hyprlauncher -o "firefox,chrome,safari"
std::vector<std::string> opts = {"firefox", "chrome", "safari"};
socket->sendOpenWithOptions(opts);
// Blocks until user selects or closes
// Then exits
```
```

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

### Usage of ui:window_size Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Demonstrates how to access and apply the 'ui:window_size' VEC2 configuration value to set the preferred size of a UI element.

```cpp
static auto PWINDOWSIZE = Hyprlang::CSimpleConfigValue<Hyprlang::VEC2>(
    g_configManager->m_config.get(), 
    "ui:window_size"
);

->preferredSize({(*PWINDOWSIZE).x, (*PWINDOWSIZE).y})
```

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

### Get Top Fuzzy Search Results

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/fuzzy.md

Ranks and filters input results based on a query using fuzzy matching. Handles multi-threading for large result sets.

```cpp
std::vector<SP<IFinderResult>> getNResults(
    const std::vector<SP<IFinderResult>>& in, 
    const std::string& query, 
    size_t results
);
```

```cpp
std::vector<SP<IFinderResult>> allApps = finder->getResultsForQuery("");
std::string userQuery = "fire";

// Get top 10 matches for "fire"
auto topMatches = Fuzzy::getNResults(allApps, userQuery, 10);

for (const auto& result : topMatches) {
    std::cout << result->name() << std::endl;
}
// Output: Firefox, Thunderbird, Firewall Settings, ...
```

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

### eLogLevel Enum Example Usage

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/types.md

Demonstrates how to use the eLogLevel enum with the Debug::log() function. Note the conditional logging for TRACE and the use of format specifiers for error messages.

```cpp
Debug::log(TRACE, "Detailed message");  // Only with --verbose
Debug::log(INFO, "Starting up");
Debug::log(ERR, "Failed to load {}", filename);
Debug::log(CRIT, "Unrecoverable error");
```

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

### Example Cache File Content

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/entrycache.md

A simple newline-separated list of entry names. Each line represents a selection event, and duplicates accumulate counts. This format is used for LRU trimming.

```plaintext
firefox
thunderbird
files
firefox
calculator
firefox
```

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

### Building Hyprlauncher with CMake

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/README.md

Standard build process for Hyprlauncher using CMake, including dependency requirements.

```bash
mkdir build
cd build
cmake ..
make
sudo make install
```

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

### Hyprlauncher Core Protocol - Client Methods

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Control the launcher window, open with choices, retrieve information, or destroy the manager object.

```cpp
set_open_state(uint state)
open_with_options(array varchar options)
get_info_object()
destroy()
```

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

### Get Desktop Application Results

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Retrieves a list of matching desktop applications based on a query string. Results are ranked by fuzzy score and usage frequency, returning up to 50 matches.

```cpp
auto results = g_desktopFinder->getResultsForQuery("firefox");
// Returns: [Firefox, Firefox Developer Edition, ...]

auto results = g_desktopFinder->getResultsForQuery("");
// Returns: All applications, sorted by frequency
```

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

### Handle User Selection

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/ipc-protocol.md

Set up a callback to be notified when the user makes a selection in the launcher. The selected item's identifier is provided.

```cpp
infoObj->setSelectionMade([](const char* selected) {
    std::cout << selected << std::endl;  // Print selection to stdout
});
```

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

### Hyprlauncher Initialization with Explicit Options

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ipcfinder.md

Initializes Hyprlauncher with a predefined list of explicit options, overriding the default query provider with an IPC finder.

```cpp
// In main()
std::vector<std::string> explicitOptions = {"firefox", "chrome", "safari"};
g_ipcFinder->setData(explicitOptions);
g_queryProcessor->overrideQueryProvider(g_ipcFinder);
g_ui->setWindowOpen(true);
```

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

### CIPCFinder::init

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ipcfinder.md

IPC finder has no initialization (data is set programmatically). This method is empty.

```APIDOC
## init()

### Description

IPC finder has no initialization (data is set programmatically). This method is empty.

### Method

`void init()`

### Parameters

None

### Return Type

`void`
```

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

### Script Integration with Hyprlauncher

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ipcfinder.md

This bash script demonstrates how to present a user with a list of actions using hyprlauncher and process their choice.

```bash
#!/bin/bash

# Present user with list of actions
choice=$(hyprlauncher -o "Edit,Delete,Rename,Cancel")

case "$choice" in
    Edit)   echo "Editing..." ;;
    Delete) echo "Deleting..." ;;
    Rename) echo "Renaming..." ;;
    Cancel) echo "Cancelled" ;;
esac
```

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

### CDesktopEntry::run()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/desktopfinder.md

Launches the application represented by the CDesktopEntry. It constructs the command based on configuration, handles desktop-specific format codes, and executes the command via /bin/sh -c, updating the usage frequency cache.

```APIDOC
## CDesktopEntry::run()

### Description
Launches the application. This method constructs the command by combining a launch prefix, terminal command (if applicable), and the application's executable. It also handles the removal of desktop-specific format codes and executes the command using `/bin/sh -c`, followed by an update to the usage frequency cache.

### Method
`virtual void run();`

### Behavior
1. Retrieves the launch prefix from the configuration (`finders:desktop_launch_prefix`).
2. Retrieves the terminal command from the configuration (`finders:desktop_terminal`).
3. Constructs the command string in the format: `[prefix] [terminal] [exec]`.
4. Removes desktop-specific format codes (e.g., `%U`, `%f`, `%F`) from the command.
5. Executes the constructed command using `/bin/sh -c`.
6. Updates the usage frequency cache for the application.

### Example
Configuration:
```ini
finders {
    desktop_launch_prefix = dbus-launch
    desktop_terminal = kitty -e
}
```

Execution for a terminal app:
```bash
/bin/sh -c "dbus-launch kitty -e /usr/bin/app"
```
```

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

### Register Desktop Launch Prefix Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Registers a string configuration value for a command prefix to be added when launching desktop entries.

```cpp
m_config->addConfigValue("finders:desktop_launch_prefix", Hyprlang::STRING{"");});
```

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

### windowOpen

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Queries the current state of the launcher window.

```APIDOC
## bool windowOpen()

### Description
Queries current window state.

### Parameters
None

### Return Type
`bool`

Returns true if the window is currently open, false otherwise.

### Request Example
```cpp
if (g_ui->windowOpen()) {
    // Window is visible
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Hyprlauncher Subsequent Launch Flow

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Describes the process when Hyprlauncher is launched subsequently, showing the client connecting to an existing daemon.

```bash
user$ hyprlauncher
  → main() creates client socket
  → Client socket connects to daemon
  → main() checks socket->m_connected
  → Client sends command to daemon
  → Client exits immediately
  
daemon (running from first launch)
  ↓ receives command via IPC
  → UI window opens/closes
```

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

### Hyprlauncher Command-Line Interface

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/README.md

Basic usage of the Hyprlauncher command-line tool.

```bash
hyprlauncher [options]
```

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

### Enable Verbose Logging

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/README.md

Run Hyprlauncher with the --verbose flag to enable TRACE level logging for detailed debugging output.

```bash
hyprlauncher --verbose
```

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

### setWindowOpen

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Opens or closes the launcher window and synchronizes the UI state accordingly.

```APIDOC
## void setWindowOpen(bool open)

### Description
Opens or closes the launcher window, with UI state synchronization.

### Parameters
#### Path Parameters
- **open** (bool) - Required - true = open, false = close

### Request Example
```cpp
// From keyboard handler
if (e.xkbKeysym == XKB_KEY_Escape) {
    g_ui->setWindowOpen(false);
}

// From IPC command
if (command == "open") {
    g_ui->setWindowOpen(true);
}
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Search IPC Options with Fuzzy and Prefix Matching

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ipcfinder.md

Demonstrates searching within the IPC options using fuzzy and prefix matching. The `getResultsForQuery` method returns matching options based on the input string.

```cpp
std::vector<std::string> opts = {"firefox", "chromium", "safari"};
g_ipcFinder->setData(opts);

// User types "fi"
auto results = g_ipcFinder->getResultsForQuery("fi");
// Returns: [firefox]  (fuzzy match)

// User types "chrome"
auto results = g_ipcFinder->getResultsForQuery("chrome");
// Returns: [chromium]  (prefix match)
```

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

### good()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/entrycache.md

Checks if the cache was successfully initialized and loaded.

```APIDOC
## bool good()

### Description
Checks if the cache was successfully initialized. Returns true if the cache file was found and loaded successfully, false otherwise. A false value usually indicates the first run or missing $HOME environment variable.

### Parameters
None

### Return Type
bool

### Example Usage
```cpp
if (m_cache->good()) {
    uint32_t freq = m_cache->getCachedEntry("firefox");
    // Use frequency for scoring
}
```
```

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

### Usage of grab_focus Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Demonstrates how to access and use the 'general:grab_focus' integer configuration value in C++ code, typically for window focus behavior.

```cpp
static auto PGRABFOCUS = Hyprlang::CSimpleConfigValue<Hyprlang::INT>(
    g_configManager->m_config.get(), 
    "general:grab_focus"
);

// In window creation
->kbInteractive(*PGRABFOCUS ? 1 : 2)
```

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

### CUI Constructor

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Initializes the CUI class, setting up all UI elements and the application window. It does not enter the event loop.

```APIDOC
## CUI(bool open)

### Description
Initializes all UI elements and creates the application window. Does NOT enter the event loop; that happens in `run()`.

### Parameters
#### Path Parameters
- **open** (bool) - Required - Whether to open the launcher by default

### Request Example
```cpp
// In main()
g_ui = makeUnique<CUI>(openByDefault);
g_ui->run();  // Enter event loop
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Command-Line Interface Arguments

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Supported command-line arguments for the Hyprlauncher executable.

```APIDOC
## Command-Line Interface

### Supported Arguments

| Argument | Purpose |
|---|---|
| `-d`, `--daemon` | Start as daemon |
| `-o`, `--options "a,b,c"` | Open with options |
| `-m`, `--dmenu` | Read from stdin |
| `-t`, `--toggle` | Toggle window |
| `-h`, `--help` | Show help |
| `-v`, `--version` | Show version |
| `--quiet` | Suppress logging |
| `--verbose` | Enable verbose logging |
```

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

### Hyprlauncher Options Mode Flow

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Details the integration flow when Hyprlauncher is launched with options, including client-daemon communication and user selection.

```bash
user$ hyprlauncher -o "a,b,c"
  → Client socket connects to daemon
  → Client sends OpenWithOptions([a,b,c])
  → Client blocks on dispatchEvents()
  → Daemon's IPCFinder gets options
  → Daemon's QueryProcessor routes to IPCFinder
  → User selects from {a,b,c}
  → Daemon sends SelectionMade("a")
  → Client receives, prints "a", exits
```

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

### Register Window Size Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Registers a VEC2 configuration value for the initial launcher window size, with a default of 400x260 pixels.

```cpp
m_config->addConfigValue("ui:window_size", Hyprlang::VEC2{400, 260});
```

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

### parse Method

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Reads and parses the current configuration file. Uses defaults if the file is missing and logs errors on failure. Called during initialization, on file changes, or manually.

```cpp
void parse();
```

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

### CUI Constructor and Methods

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Manages the user interface, including window state and result updates.

```cpp
CUI(bool open);
~CUI();
void run();
void setWindowOpen(bool open);
bool windowOpen();
void updateResults(std::vector<SFinderResult>&& results);
void updateActive();
```

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

### run

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ui.md

Enters the main event loop for the UI, blocking until the application exits.

```APIDOC
## void run()

### Description
Starts the main event loop. This blocks until the application exits.

### Parameters
None

### Return Type
`void`

### Request Example
```cpp
g_ui = makeUnique<CUI>(true);  // open by default
g_ui->run();  // Block in event loop until exit
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Register Default Finder Configuration

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/configmanager.md

Registers a string configuration value to specify the default finder, with 'desktop' as the default.

```cpp
m_config->addConfigValue("finders:default_finder", Hyprlang::STRING{"desktop"});
```

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

### run()

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/ifinderresult.md

Executes the action associated with this result, such as launching an application or copying text to the clipboard.

```APIDOC
## run()

### Description
Executes the action associated with this result.

### Method
virtual void run() = 0

### Return Type
void

### Description
Executes the primary action for this result. The specific behavior depends on the result type:

- **Desktop results:** Launch the application
- **Unicode results:** Copy character to clipboard via `wl-copy`
- **Math results:** Copy evaluated result to clipboard
- **IPC results:** Return selection to client
- **Font results:** Copy font name to clipboard

This method is called when the user selects a result and presses Enter in the UI.

### Example Usage:
```cpp
std::vector<SFinderResult> results = finder->getResultsForQuery("calc");
if (!results.empty()) {
    results[0].result->run();  // Execute the selected result
}
```
```

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

### sendOpen Method for CClientIPCSocket

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Sends a command to the running daemon to open its launcher window. This method is used when a client is successfully connected.

```cpp
void sendOpen();
```

```cpp
if (socket->m_connected) {
    socket->sendOpen();  // Open daemon's launcher
    return 0;
}
```

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

### Logging with Different Levels

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/README.md

Demonstrates how to log messages at different severity levels using the Debug::log function. Use TRACE for detailed information and ERR for error reporting.

```cpp
Debug::log(TRACE, "Detailed info");
Debug::log(ERR, "Something failed: {}", reason);
```

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

### Initialize CQueryProcessor

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/queryprocessor.md

Initializes the global CQueryProcessor instance. This is typically called once during application startup.

```cpp
// Called automatically once
g_queryProcessor = makeUnique<CQueryProcessor>();
```

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

### CQueryProcessor Constructor and Destructor

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Initializes and cleans up the query processing system.

```cpp
CQueryProcessor();
~CQueryProcessor();
```

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

### CDesktopFinder Methods

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Implements finder functionality specific to the desktop environment, including inotify event handling.

```cpp
CDesktopFinder();
virtual ~CDesktopFinder() = default;
virtual std::vector<SFinderResult> getResultsForQuery(const std::string& query);
virtual void init();
void onInotifyEvent();
```

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

### CConfigManager Constructor and Methods

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Manages configuration parsing and file system watch events.

```cpp
CConfigManager();
void parse();
void onInotifyEvent();
void replantWatch();
```

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

### Hyprlauncher Selection Flow

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/REFERENCE_INDEX.md

Details the process initiated when a user presses Enter, from selecting an item to executing an action, updating the cache, and finally closing the launcher.

```text
User presses Enter
    ↓
CUI::onSelected()
    ↓
IFinderResult::run()
    ↓
Action executes (launch, copy, etc)
    ↓
CEntryCache::incrementCachedEntry()
    ↓
Cache persisted to disk
    ↓
CServerIPCSocket::sendSelectionMade()
    ↓
Launcher closes
```

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

### CClientIPCSocket Constructor

Source: https://github.com/hyprwm/hyprlauncher/blob/main/_autodocs/api-reference/socket.md

Attempts to connect to the running hyprlauncher daemon via Unix domain socket. Sets `m_connected = true` if successful, false otherwise.

```APIDOC
## CClientIPCSocket()

### Description
Attempts to connect to the running hyprlauncher daemon via Unix domain socket. Sets `m_connected = true` if successful, false otherwise.

### Connection Process:
1. Reads `$XDG_RUNTIME_DIR` environment variable
2. Constructs socket path: `{XDG_RUNTIME_DIR}/.hyprlauncher.sock`
3. Attempts to open connection via `Hyprwire::IClientSocket::open()`
4. Creates protocol implementation and adds to socket
5. Waits for server handshake
6. Binds protocol and creates manager object
7. Sets `m_connected = true` if all steps succeed

### Example Usage:
```cpp
// In main()
auto socket = makeShared<CClientIPCSocket>();

if (socket->m_connected) {
    // Connected to daemon
    socket->sendOpen();
} else {
    // No daemon running; this process will become the daemon
    g_serverIPCSocket = makeUnique<CServerIPCSocket>();
}
```
```