HandyCafe Docs
owner it-admin

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

  1. Open the HandyCafe Server application and navigate to Settings in the left sidebar.
  2. Select the Clients tab at the top, then switch to the Content sub-tab.
  3. In the Categories panel on the left, click the Add Category button.
  4. Enter a category name such as "Games" or "Browsers" and confirm. The new category appears in the list.
  5. Select the category you just created. In the right panel, click Add App.
  6. 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.
  7. 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.
  8. 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.
  9. Optionally upload a Poster Image for a richer visual card. This is the large artwork shown in poster-first display modes. You can also enable the Hero Carousel toggle to feature this app in the rotating banner at the top of the client desktop.
  10. 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. You choose a color theme, a layout preset, card density, and background settings.

What you will need

  • HandyCafe Server running.
  • For image or video backgrounds: media files in PNG, JPG, WebP, MP4, or WebM format.

Steps

  1. Navigate to Settings > Clients > Appearance tab.
  2. Under Theme, select one of the available color themes: Neon Arena (blue-purple gaming aesthetic), Crimson Pulse (red-dark tones), or Emerald Depth (green-teal palette). A preview updates as you make selections.
  3. Under Layout Preset, choose how content is arranged on screen. Options are Split Classic (categories on the left, apps on the right), Hero Wide Top (large hero carousel at top, apps below), Catalog Wide Bottom (compact hero, wider app grid), or Compact Focus (minimal chrome, maximum app space).
  4. Set Card Density to control how many apps fit on screen at once. Large shows bigger cards with more detail. Medium balances size and quantity. Compact fits the most apps per row.
  5. Configure the Background. Select the type: Solid (pick a color), Gradient (pick two colors), Image (upload a file), or Video (upload an MP4/WebM). For Image and Video types, adjust the Overlay Opacity slider to darken the background behind cards, and the Blur slider to soften it.
  6. Click Save. The theme pushes to all connected clients immediately.

Expected result

Client desktops refresh with the new visual settings. The theme, layout, 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.

How to Configure the Idle Screen

The idle screen is what customers see when a PC is not in use. It can display a slideshow of images or videos, a clock, and your cafe name.

What you will need

  • Image files (PNG, JPG, WebP, or GIF) or video files (MP4, WebM) for the slideshow.
  • HandyCafe Server running.

Steps

  1. Navigate to Settings > Clients > Idle Screen tab.
  2. Toggle Enable Slideshow to on.
  3. Click Add Media to upload images or videos. You can add multiple items. Supported formats are PNG, JPG, WebP, GIF, MP4, and WebM.
  4. Set the Duration for each item in seconds. This controls how long each slide stays visible before transitioning. A value between 8 and 15 seconds works well for most setups.
  5. Choose a Transition effect: Fade (smooth opacity crossfade), Slide (horizontal slide), or Zoom (scale-in effect).
  6. Enable the Clock Overlay toggle to display a digital clock on the idle screen. Use the color picker to set the clock text color for maximum contrast against your slideshow content.
  7. Enable the Cafe Name toggle to show your business name on the idle screen. The name is pulled from your general server settings.
  8. Click Save. The idle screen configuration pushes to all connected clients.

Expected result

Client PCs that are not in an active session display the slideshow with the configured transitions, clock overlay, and cafe name. The 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.
  • Not testing the clock color against all slideshow images. A white clock is invisible on a bright white slide. Pick a color that works across your entire slideshow set.

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

  1. Navigate to Settings > Clients > Content tab.
  2. Scroll to the Announcements section below the app categories.
  3. Click Add Announcement.
  4. Enter a Title and Text for the announcement. If linking to an external page, enter the Link URL.
  5. 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.
  6. Set the Category to classify the announcement: Link, Game, Announcement, or Ad. This determines where it appears in the client layout.
  7. 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.