HNClient Class Reference

Client-side entry point of the Heaven library. More...

#include "HNClient.h"

Public Member Functions
void	commit () noexcept
	Requests the bar process to apply all pending changes.
const std::string &	name () const noexcept
	Returns the application name advertised to the bar.
void	setName (const std::string &name) noexcept
	Sets the application name advertised to the bar.
HNTopbar *	activeTopbar () const noexcept
	Returns the topbar currently marked as active.
void	setActiveTopbar (HNTopbar *topbar) noexcept
	Marks a topbar as the one that should currently be displayed.
void	setPrivateHandle (const std::string &handle) noexcept
	Sets the compositor-assigned private Wayland handle.
const std::string &	privateHandle () const noexcept
	Returns the private Wayland handle associated with this client.
const std::string &	barId () const noexcept
	Returns the D-Bus unique name of the connected bar process.
const std::string &	compositorId () const noexcept
	Returns the D-Bus unique name of the connected compositor process.
std::shared_ptr< CZBus >	bus () const noexcept
	Returns the shared Cuarzo Core D-Bus instance.

Static Public Member Functions
static std::shared_ptr< HNClient >	GetOrMake () noexcept
	Returns the existing HNClient instance or creates it if doesn't exist.
static std::shared_ptr< HNClient >	Get () noexcept
	Returns the existing HNClient singleton instance.

Detailed Description

Client-side entry point of the Heaven library.

A single HNClient instance manages the connection to the bar and compositor, owns the object-id allocator, and batches menu changes until commit(). Menu objects (HNTopbar, HNMenu, …) are created through their own Make() factories and reference the client that owns them.

The instance is a lazily-created singleton; retrieve it with GetOrMake().

Member Function Documentation

activeTopbar()

HNTopbar * activeTopbar ( ) const

inlinenoexcept

Returns the topbar currently marked as active.

Returns

Pointer to the active topbar, or nullptr if none is set.

barId()

const std::string & barId ( ) const

inlinenoexcept

Returns the D-Bus unique name of the connected bar process.

Returns

The bar process D-Bus ID, or an empty string if the connection has not been established.

bus()

std::shared_ptr< CZBus > bus ( ) const

inlinenoexcept

Returns the shared Cuarzo Core D-Bus instance.

Provides access to the underlying D-Bus connection used for communication with the compositor and bar processes.

Returns

Shared pointer to the active CZBus instance.

commit()

void commit ( )

noexcept

Requests the bar process to apply all pending changes.

Signals the bar to process all queued updates atomically, including object creation requests, property updates, and state changes.

If called before the connection with the bar has been established, the pending state is retained and sent once the connection becomes available.

compositorId()

const std::string & compositorId ( ) const

inlinenoexcept

Returns the D-Bus unique name of the connected compositor process.

Returns

The compositor process D-Bus ID, or an empty string if the connection has not been established.

Get()

static std::shared_ptr< HNClient > Get ( )

staticnoexcept

Returns the existing HNClient singleton instance.

Unlike GetOrMake(), this method does not create a new instance if one has not already been initialized.

Returns

Shared pointer to the existing HNClient instance, or nullptr if no instance has been created yet.

GetOrMake()

static std::shared_ptr< HNClient > GetOrMake ( )

staticnoexcept

Returns the existing HNClient instance or creates it if doesn't exist.

Retrieves the shared singleton instance of HNClient. If the instance does not already exist, a new one is created and initialized.

Returns

Shared pointer to the singleton HNClient instance.

name()

const std::string & name ( ) const

inlinenoexcept

Returns the application name advertised to the bar.

Returns

Const reference to the application name (may be empty).

privateHandle()

const std::string & privateHandle ( ) const

inlinenoexcept

Returns the private Wayland handle associated with this client.

The handle is assigned by the compositor through the lvr-private-handle protocol and is used to associate the Wayland client with its D-Bus identity.

Returns

The private handle, or an empty string if it has not been set.

setActiveTopbar()

void setActiveTopbar ( HNTopbar *  topbar )

noexcept

Marks a topbar as the one that should currently be displayed.

Clients typically set this to the topbar associated with their active window. The change is delivered to the bar on the next commit().

Parameters

topbar

Topbar to mark active, or nullptr to leave it unchanged.

setName()

void setName ( const std::string &  name )

noexcept

Sets the application name advertised to the bar.

The change is delivered to the bar on the next commit() (or immediately if a connection is already established and the first commit has occurred).

Parameters

name	New application name.

setPrivateHandle()

void setPrivateHandle ( const std::string &  handle )

noexcept

Sets the compositor-assigned private Wayland handle.

The handle is provided through the lvr-private-handle Wayland protocol.

After being set, the handle is forwarded over D-Bus so the compositor can associate the Wayland client instance with its corresponding D-Bus id.

This method is expected to be called exactly once during client initialization.

Parameters

handle

Private handle received from the lvr-private-handle protocol.

---

The documentation for this class was generated from the following file:

• /home/runner/work/Heaven/Heaven/src/CZ/Heaven/Client/HNClient.h