File Reference

Descriptions of every source file, key data structures, and important functions.

Contents

Source Files

main.h

Central header included by every .c file. Contains:

main.c

Entry point and main window procedure.

resource.h

All #define IDs for menus, dialogs, and controls. Grouped by:

window.c

Window creation, tab bar, tray icon, and popup menu.

tabs.c

Tab switching and script button management.

paint.c

All GDI rendering. Every function uses double-buffering (memory DC + BitBlt).

github.c

All GitHub API communication.

sync.c

GitHub sync thread and local directory scanning.

runner.c

Script execution and dependency management.

meta.c

Parses the metadata header from PyCATIA script files.

Header format expected (see Writing Your Own Scripts in the user guide for full details):

'''
    -------...------
    Script name:    My_Script.py
    Version:        1.0
    Purpose:        One line summary.
    Author:         Your Name
    Date:           DD.MM.YY
    Description:    Full description.
                    Continuation line.
    -------...------
'''

Scripts use the PyCATIA library for CATIA V5 COM automation.

help.c

In-app help window implementation.

prefs.c

User preferences persistence and script management dialogs.

sources.c

Sources dialog for managing extra repos and local folders.

settings.c

Settings persistence and dialogs.

updater.c

Checks GitHub Releases API for newer versions.

quickbar.c

Floating Quick Launch Bar — a small always-on-top button bar that mirrors the ⭐ Favourites tab.

Public API (called from main.c and window.c):

Internal key functions:

Key Structs

SortMode / ThemeMode (enums)

typedef enum {
    SORT_ORDER    = 0,  /* order from GitHub API / disk                */
    SORT_ALPHA    = 1,  /* alphabetical A-Z                            */
    SORT_DATE     = 2,  /* by script header Date: field                */
    SORT_MOST_USED = 3  /* by run count descending                     */
} SortMode;

typedef enum { THEME_SYSTEM = 0, THEME_DARK = 1, THEME_LIGHT = 2 } ThemeMode;

SyncStatus / SyncResult

Communicates the outcome of a background sync from Sync_Thread to the main window via WM_SYNC_DONE. The SyncResult pointer is passed as wParam; Handle_SyncDone reads it and frees it.

typedef enum { SR_OK=0, SR_NO_INTERNET, SR_API_ERROR, SR_PARTIAL } SyncStatus;

typedef struct {
    SyncStatus status;
    int folders_added, folders_removed;
    int scripts_updated, scripts_added, scripts_removed;
    WCHAR message[256];
} SyncResult;

ExtraRepo

One user-added GitHub repository script source. Loaded from settings.ini and passed to Sync_ExtraRepo.

typedef struct {
    WCHAR url[512];
    WCHAR branch[64];
    WCHAR token[256];
    bool  enabled;
} ExtraRepo;

LocalDir

One user-added local folder script source. Loaded from settings.ini and passed to Sync_LocalDir.

typedef struct {
    WCHAR path[MAX_APPPATH];
    bool  enabled;
} LocalDir;

ScriptMeta

Parsed header fields from a script file. Populated by Meta_Parse; read by Paint_Tooltip, ScriptDetailsDlgProc, and Tabs_ApplySort.

typedef struct {
    WCHAR purpose[128];
    WCHAR author[64];
    WCHAR version[32];
    WCHAR date[32];
    WCHAR description[1024];
    WCHAR code[64];        /* e.g. "Python3.10.4, Pycatia 0.8.3"       */
    WCHAR release[32];     /* e.g. "V5R32"                              */
    WCHAR requirements[512];
} ScriptMeta;

AppState (g)

The single global state struct. All state lives here.

typedef struct {
    HWND   hwnd;           /* main window */
    HWND   hwnd_tab;       /* custom tab bar (CMW32TabBar) */
    HWND   hwnd_scroll;    /* scroll panel containing script buttons */
    HWND   hwnd_status;    /* custom status bar (CMW32StatusBar) */
    HWND   hwnd_tip;       /* tooltip popup */
    HWND   hwnd_search;    /* search/filter edit box */
    HWND   hwnd_details;   /* script details panel */

    ScriptFolder folders[MAX_FOLDERS];  /* all loaded folders/tabs */
    int      folder_count;
    int      active_tab;
    int      tab_offset;   /* first visible tab when scrolling */
    Settings cfg;
    bool     dark_mode;    /* resolved from cfg.theme + system setting */

    HFONT  font_ui;        /* Segoe UI 13px normal */
    HFONT  font_bold;      /* Segoe UI 13px semibold */
    HFONT  font_small;     /* Segoe UI 11px normal */
    HBRUSH br_bg, br_toolbar, br_btn, br_btn_hot, br_accent, br_status;

    bool   syncing;
    bool   status_offline; /* true when showing stale cache due to no internet */
    int    hot_btn;        /* currently hovered script button ID */
    int    tip_btn;        /* button whose tooltip is showing */
    int    tip_h;          /* cached tooltip height */
    WCHAR  last_run_path[MAX_APPPATH];
    WCHAR  appdata_dir[MAX_APPPATH];
    WCHAR  latest_version[32];         /* from GitHub releases API */
    WCHAR  active_folder_name[MAX_NAME]; /* folder name saved by Tabs_Switch for post-sync restoration */
    int    scroll_y, scroll_max;
    bool   tray_icon_added;

    CRITICAL_SECTION cs_folders;  /* guards folders[] and folder_count between sync and UI threads */
    volatile HANDLE run_process;  /* duplicated handle of bg script process; NULL when idle */

    /* Filter */
    WCHAR  filter_text[MAX_NAME]; /* current search/filter string */

    /* Details panel */
    int    details_script_fi;    /* folder index of shown script */
    int    details_script_si;    /* script index of shown script */
    bool   details_visible;

    /* Quick Launch Bar */
    HWND   hwnd_qbar;            /* floating bar window */
    HWND   hwnd_qbar_tip;        /* bar tooltip popup */
    int    qbar_hot;             /* hovered button index, -1 = none */
    int    qbar_scroll;          /* current scroll offset (px) */
    int    qbar_scroll_max;      /* maximum scroll offset */
    bool   qbar_dragging;
    int    qbar_drag_ox;         /* drag start: cursor offset from left */
    int    qbar_drag_oy;         /* drag start: cursor offset from top */
    int    qbar_tip_idx;         /* button index shown in tip, -1 = none */

    /* Double-click repeat mode */
    bool   repeat_mode;          /* true while a script is looping */
    int    repeat_fi;            /* folder index of the script to repeat */
    int    repeat_si;            /* script index of the script to repeat */
    bool   suppress_lbuttonup;   /* suppresses extra WM_LBUTTONUP after WM_LBUTTONDBLCLK */

    /* Running state (background mode only) */
    bool   script_running;       /* true while a background script is in flight */
    int    run_fi;               /* folder index of the running script */
    int    run_si;               /* script index of the running script */
} AppState;

Settings

All user-configurable options. Loaded from/saved to settings.ini.

typedef struct {
    WCHAR     python_exe[MAX_APPPATH];
    WCHAR     cache_dir[MAX_APPPATH];
    WCHAR     github_token[256];
    bool      auto_sync, download_before_run;
    bool      show_console, console_keep_open, deps_keep_open;
    bool      always_on_top, minimize_to_tray;
    bool      start_with_windows, start_minimized;
    bool      check_updates;
    bool      auto_update;       /* auto-download and install updates */
    bool      offline_use_cache; /* show cached scripts when offline (default: false) */
    ThemeMode theme;             /* THEME_SYSTEM=0, THEME_DARK=1, THEME_LIGHT=2 */
    int       refresh_interval;  /* hours, 0 = disabled, default 6 */
    bool      main_repo_enabled;
    ExtraRepo extra_repos[MAX_EXTRA_REPOS];
    int       extra_repo_count;
    LocalDir  local_dirs[MAX_LOCAL_DIRS];
    int       local_dir_count;
    SortMode  sort_mode;         /* global sort mode */
    /* Quick Launch Bar */
    bool      qbar_enabled;
    bool      qbar_horizontal;
    bool      qbar_topmost_with_catia;
    int       qbar_x, qbar_y;
    WCHAR     qbar_target_app[MAX_NAME]; /* window-title substring; empty = no target */
    WCHAR     qbar_target_exe[MAX_NAME]; /* process exe name (e.g. CNEXT.exe); empty = any */
    bool      repeat_on_dblclick;        /* repeat main-window scripts on double-click */
    bool      qbar_repeat_on_dblclick;   /* repeat Quick Bar scripts on double-click */
} Settings;

ScriptFolder

One tab worth of scripts.

typedef struct {
    WCHAR    name[MAX_NAME];    /* raw folder name e.g. "Any_Document_Scripts" */
    WCHAR    display[MAX_NAME]; /* formatted e.g. "Any Document Scripts" */
    Script  *scripts;           /* heap-allocated; use Folder_Alloc / Folder_Free */
    int      count;
    int      capacity;          /* number of allocated slots */
    bool     loaded;
    SortMode sort_mode;
} ScriptFolder;

Folder_Alloc, Folder_Free, and Folder_Push are inline helpers in main.h. Folder_Push doubles capacity automatically when count == capacity.

Script

One script button.

typedef struct {
    WCHAR      name[MAX_NAME];       /* display name */
    WCHAR      gh_path[MAX_APPPATH]; /* GitHub API path e.g. "folder/script.py" */
    WCHAR      sha[MAX_SHA];         /* expected blob SHA from GitHub API */
    WCHAR      local[MAX_APPPATH];   /* local cache path */
    ScriptMeta meta;
    bool       meta_loaded;
    bool       is_favourite;
    bool       is_hidden;
    int        run_count;
    WCHAR      note[MAX_NOTE_LEN];
} Script;

Constants and Limits

String / buffer limits

Constant Value Description
MAX_FOLDERS 64 Maximum number of tabs
MAX_SCRIPTS 1024 Default initial capacity per folder (heap grows dynamically)
MAX_EXTRA_REPOS 8 Maximum extra GitHub repos
MAX_LOCAL_DIRS 8 Maximum local folders
MAX_FAVOURITES 256 Maximum entries in the favourites list in prefs.ini
MAX_HIDDEN 256 Maximum entries in the hidden-scripts list in prefs.ini
MAX_NAME 128 Wide character buffer for names, tab labels, filter text
MAX_SHA 64 Wide character buffer for a Git blob SHA1 hex string
MAX_APPPATH 520 Wide character buffer for file-system paths
MAX_NOTE_LEN 512 Wide character buffer for per-script user notes
HTTP_BUF_SIZE 512 KB HTTP response read buffer

Layout constants

Constant Value Description
WIN_MIN_W 820 Minimum window width in pixels
WIN_MIN_H 420 Minimum window height in pixels
TOOLBAR_H 38 Toolbar height in pixels
TAB_H 26 Tab bar height in pixels
TAB_ARROW_W 22 Tab scroll arrow width
STATUS_H 22 Status bar height
SEARCH_H 26 Search/filter box height
BTN_H 40 Script button height
BTN_GAP 6 Vertical gap between script buttons
BTN_MX 12 Script button horizontal margin
BTN_MY 10 Script button vertical margin
INFO_BTN_W 28 Width of the i info badge
STAR_BTN_W 28 Width of the favourite star badge
TIP_W 320 Script tooltip popup width
QBAR_BTN_SIZE 52 Quick bar button face square (px)
QBAR_PAD 4 Margin from bar edge to buttons
QBAR_GAP 4 Gap between adjacent bar buttons
QBAR_ARROW_W 18 Quick bar scroll arrow click area
QBAR_TIP_W 240 Quick bar tooltip popup width
QBAR_TIP_PAD 8 Quick bar tooltip internal padding
QBAR_TIP_ROW 18 Quick bar tooltip row height

Message IDs

Message Value Direction Description
WM_SYNC_DONE WM_USER+1 Thread → Main Sync completed; wParam is heap SyncResult* (freed by handler)
WM_STATUS_SET WM_USER+2 Thread → Main Update status bar; lParam is heap WCHAR* (freed by handler)
WM_TRAYICON WM_USER+10 System → Main Tray icon mouse event
WM_UPDATE_AVAIL WM_USER+11 Thread → Main Newer version found
WM_AUTO_REFRESH WM_USER+12 Timer → Main Auto-refresh interval elapsed
WM_SCRIPT_STARTED WM_USER+13 Runner → Main Background script launched; enables the Stop button and turns the running button green
WM_SCRIPT_STOPPED WM_USER+14 Runner → Main Background script exited or was terminated; disables the Stop button and clears the green highlight

Timer IDs

Constant Value Description
TIMER_AUTO_REFRESH 1001 SetTimer ID for the periodic auto-sync interval
TIMER_QBAR 1002 SetTimer ID used by the Quick Launch Bar for visibility polling

Colour System

All colours are defined as #define pairs (dark/light) and accessed via inline runtime functions that check g.dark_mode:

// Defined as macros:
#define COL_BG_DARK    RGB(28,  28,  35)
#define COL_BG_LIGHT   RGB(240, 240, 245)

// Accessed via inline function:
static inline COLORREF COL_BG(void) {
    return g.dark_mode ? COL_BG_DARK : COL_BG_LIGHT;
}

Runtime accessor functions (dark/light):

Function Dark Light Used for
COL_BG() #1C1C23 #F0F0F5 Main window background
COL_TOOLBAR() #141418 #D2D2DC Toolbar and tab bar
COL_BTN_NORM() #2C2E40 #DCDEED Script button normal
COL_BTN_HOT() #3E415A #BEC3DC Script button hover
COL_BTN_PRESS() #1C1E30 #AAAFCD Script button pressed
COL_INFO_ZONE() #24263A #C8CAD8 Script button info badge zone
COL_TEXT() #D2D7F0 #1E1E28 Primary text
COL_SUBTEXT() #6E7494 #646478 Secondary text, purposes
COL_DIVIDER() #2E3042 #BEC0D2 Separators and borders
COL_TIP_BG() #161620 #F5F5FC Tooltip background

Fixed-colour constants (no theme variant):

Constant Value Used for
COL_ACCENT RGB(82, 155, 245) Highlights, selected tabs, accent bars
COL_ACCENT_DIM RGB(48, 92, 160) Dimmed accent for pressed states
COL_SUCCESS RGB(80, 200, 120) Success/OK indicators; running script button highlight
COL_WARN RGB(240, 190, 60) Warning status indicators
COL_STAR RGB(255, 200, 60) Favourite star badge
COL_TIP_BORDER RGB(82, 155, 245) Tooltip popup border