How to Configure the Client Desktop
This guide walks you through building the app menu that customers see on their PCs, applying visual themes, setting up the idle screen, and publishing announcements. Every change you make on the server is pushed to connected clients instantly over TCP.
How to Build the App Menu
The app menu is what customers interact with during their session. It is organized into categories, each containing one or more apps. You manage the entire catalog from the server.
What you will need
- HandyCafe Server running with at least one client connected.
- App executables already installed on the client PCs (for Game and App kinds).
- Icon images (PNG, JPG, or WebP) ready for upload. Recommended size is 128x128 pixels.
Steps
- Open the HandyCafe Server application and navigate to Settings in the left sidebar.
- Select the Clients tab at the top, then switch to the Content sub-tab.
- In the Categories panel on the left, click the Add Category button.
- Enter a category name such as "Games" or "Browsers" and confirm. The new category appears in the list.
- Select the category you just created. In the right panel, click Add App.
- Fill in the app details. Enter a Name (for example "Counter-Strike 2"), an optional Description, and set the Kind field to the appropriate type: Game, Browser, Link, File, or App.
- In the Executable Path field, enter the full path to the application on the client PC. For example:
C:\Program Files\Steam\steamapps\common\CS2\cs2.exe. For Link kind, enter a URL instead. - Upload an icon by clicking the icon area. You can paste a URL to fetch an image from the web or browse for a local file on your machine. The icon displays in the client app grid.
- Optionally upload a Poster Image for a richer visual card. This is the large artwork shown on the app card. You can also turn on Featured to show this app in the featured area of the client desktop.
- Drag items in the category list or app list to reorder them. Toggle the visibility switch next to any app to hide it without deleting. Click Save when finished.
Expected result
All connected client desktops update within seconds. The new category and apps appear in the client app grid. Customers can launch apps by clicking their cards.
Common mistakes
- Entering a path that does not exist on the client PC. The app card will appear but launching will fail. Always verify the executable path on an actual client machine.
- Forgetting to save after making changes. Unsaved edits are not pushed to clients.
- Using oversized images without compression. While any resolution works, images larger than 512x512 slow down the sync for no visual benefit at card size.
How to Set the Desktop Theme
Themes control the overall look of the client desktop during an active session in Game Mode. You choose a design theme, poster and card settings, and the background. See Client Appearance for every option.
What you will need
- HandyCafe Server running.
- For image or video backgrounds: media files in PNG, JPG, WebP, MP4, or WebM format.
Steps
- Navigate to Settings > Clients > Appearance tab.
- Under Design Theme, select one of the 21 themes. They are grouped as Essentials (Arena, Cinema, Tablet), Color variants (for example Neon Arena, Crimson Pulse or Amethyst Surge) and Immersive scenes (for example Starforge, Magma or Blueprint). Each card shows the theme's character in one line.
- In the Global Online Layout panel, set Poster ratio and Card density. Large shows bigger cards with more detail. Medium balances size and quantity. Compact fits the most apps per row.
- Set how the featured items change: Featured carousel interval (seconds) or Enable featured animation, depending on the theme, and Featured animation type.
- Configure the background under Background type: Solid color (pick a color), Gradient (enter the gradient CSS), Image or Video (press Select media). For every type except a solid color, adjust Overlay opacity to darken the background behind cards and Blur to soften it.
- Click Save. The theme pushes to all connected clients immediately.
If the clients run in Desktop Mode, they show a floating panel instead of a themed full screen. The Appearance tab then offers Desktop Color Scheme (Dark or Light). See Client Display Modes.
Expected result
Client desktops refresh with the new visual settings. The theme, card sizes and background all update without requiring clients to restart.
Common mistakes
- Using a video background with a very large file size. Keep videos under 20 MB for fast sync. Longer or higher-resolution videos cause noticeable load times on client PCs.
- Setting overlay opacity too low on a busy background image. Text and card labels become hard to read. An overlay of 40-60% works well for most images.
- Picking an immersive theme for older client hardware. Immersive scenes carry a heavier interface. Use an essential or a colour variant there.
How to Configure the Idle Screen
The idle screen is what customers see when a PC is not in use. It can show HandyCafe's built-in animation, your own images and videos, a showcase of your game artwork, or a mix of these.
What you will need
- Image or video files for a Media slideshow.
- Poster or cover images on the games in your client menu catalog for the Gamer showcase.
- HandyCafe Server running.
Steps
- Navigate to Settings > Clients > Idle Screen tab.
- Under Screen Mode, choose one of four modes:
- Standard: HandyCafe's built-in ambient animation. No extra setup needed.
- Media: your own images and videos in a slideshow.
- Gamer: game artwork from your client menu catalog, with cinematic transitions.
- Mix: rotates randomly between the modes you pick.
- For Media, click Add Media to add images or videos to the Media Playlist. Set each item's Duration in seconds, then set the Transition, Transition Speed, Playback Order (Sequential or Random) and Display Mode (Cover, Contain or Stretch) under Slideshow Settings.
- For Gamer, adjust the Gamer Showcase Settings, such as Slide Duration, Transition Effect, Poster Frame and Poster Tilt.
- For Mix, tick at least two modes under Included Modes and set the Switch Interval. Media and Gamer use the settings from their own modes.
- Under Overlay Elements, turn on Show Clock and Show Computer Name if you want them. They apply to every mode.
- Click Save. The idle screen configuration pushes to all connected clients.
Expected result
Client PCs that are not in an active session show the chosen mode. A Media slideshow loops continuously.
Common mistakes
- Adding too many high-resolution images without considering sync time. Each media file must transfer to every client. Keep the total slideshow size reasonable.
- Setting the duration too short (under 3 seconds). Rapid transitions can feel jarring and make it difficult to read any text in the slides.
- Choosing Gamer before the games in the catalog have poster or cover images. The tab warns that no game artwork is available yet.
How to Create an Announcement
Announcements appear on client desktops and can promote events, share news, or display advertisements. The system tracks impressions and clicks automatically.
What you will need
- HandyCafe Server running with at least one client connected.
- A banner image (recommended 1200x400 pixels or wider) if you want a visual announcement.
Steps
- Navigate to Settings > Clients > Content tab.
- Scroll to the Announcements section below the app categories.
- Click Add Announcement.
- Enter a Title and Text for the announcement. If linking to an external page, enter the Link URL.
- Set the Type field. Choose Announcement for general news, Event for time-limited promotions with interactive form fields, or Text for simple text-only messages.
- Set the Category to classify the announcement: Link, Game, Announcement, or Ad. This determines where it appears in the client layout.
- Upload a Banner Image by clicking the image area and selecting a file. The banner displays in the announcement bar on the client desktop. Click Save.
Expected result
The announcement appears on connected client desktops in the announcement bar. As customers view and interact with it, the server tracks Impression Count (how many times it was displayed) and Click Count (how many times a customer clicked it).
Common mistakes
- Creating announcements without a banner image. Text-only announcements without an image are easy for customers to overlook in the announcement bar.
- Forgetting to set an expiry or remove outdated announcements. Old promotions left active create a poor customer experience.
- Using very long text in the announcement body. The display area is compact. Keep text concise and put details behind the link.