php-tkui

On Windows, you must install a Tcl/Tk binary distribution and explicitly tell php-tkui where the DLL files are located by updating your .env file.

WINDOWS_LIB_TCL=c:\\tcltk\\bin\\tcl86t.dll
WINDOWS_LIB_TK=c:\\tcltk\\bin\\tk86t.dll

To build Tcl and Tk for Windows, use the MSYS2 environment with the UCRT64 toolchain. This process involves installing dependencies via pacman, navigating to the project's tools directory, and executing the make command with the OS=win environment variable.

Prerequisites

1. Install MSYS2 from https://www.msys2.org/.
2. Launch the MSYS2 UCRT64 terminal.

Build Steps

1. Update the system and install build dependencies:

   pacman -Syuu
   pacman -S mingw-w64-ucrt-x86_64-gcc make git zip wget

2. Navigate to the project's tools directory.
3. Run the build command:

   OS=win make dist

Output

The resulting tcltk.zip file will be located in the .build directory.

# Install dependencies
pacman -Syuu
pacman -S mingw-w64-ucrt-x86_64-gcc make git zip wget

# Build
cd tools
OS=win make dist

To get started with php-tkui, ensure you have the requirements met, then clone the repository and use Composer to install dependencies. You can run the included demos to verify your installation.

Prerequisites

• PHP >= 8.2
• ffi extension enabled
• Tcl/Tk >= 8.6 installed on your OS

Installation Steps

1. Clone the repository.
2. Install dependencies via Composer.
3. Run a demo script (e.g., demos/buttons.php).

git clone https://github.com/skoro/php-tkui.git php-tkui
cd php-tkui
composer install
php demos/buttons.php

On macOS, install Tcl/Tk (e.g., via brew install tcl-tk) and then specify the paths to the .dylib files in your .env file.

brew install tcl-tk

DARWIN_LIB_TCL=/usr/local/Cellar/tcl-tk/[installed_version]/lib/libtcl8.6.dylib
DARWIN_LIB_TK=/usr/local/Cellar/tcl-tk/[installed_version]/lib/libtk8.6.dylib

Configuration is managed through a .env file. Copy .env.example to .env to begin customizing your application settings.

Debug Mode

Enabling debug mode allows you to see which commands are being executed by the Tcl engine. Set DEBUG=true and specify a destination for logs using DEBUG_LOG (e.g., php://stdout for console output or a file path).

Application Appearance (Themes)

Use the THEME option to set the visual style of your application.

• Default: THEME=auto (selects a theme based on your OS).
• Cross-platform themes: clam, alt, default, classic.
• Windows-specific themes: winnative, xpnative, vista.

DEBUG=true
DEBUG_LOG=php://stdout
THEME=auto

To create a GUI application using TkApplication, you must first instantiate it with a Tk instance. You then call init() to initialize the Tcl/Tk libraries and the ttk package (if available), and finally call run() to start the main event loop. To close the application and clean up widgets, use quit().

Note that init() handles the setup of the Tcl interpreter, argv arguments, and the ttk theme manager.

// Assuming $tk is an instance of Tk
$app = new TkApplication($tk, ['arg1' => 'val1']);
$app->init();

// ... build your UI ...

$app->run();

When instantiating a Text widget, you can pass an array of options to customize its behavior and appearance. Supported keys include:

• autoSeparators: (null)
• blockCursor: (null)
• endLine: (null)
• height: (null)
• inactiveSelectBackground: (null)
• insertUnfocussed: (null)
• font: (null)
• maxUndo: (null)
• spacing1: (null)
• spacing2: (null)
• spacing3: (null)
• startLine: (null)
• state: (null)
• tabs: (null)
• tabStyle: (null)
• undo: (null)
• width: (null)
• wrap: (null)

When creating a Listbox, you can pass the following options in the $options array:

The Notebook widget supports the following configuration options via TclOptions:

Note: The implementation suggests padding may eventually require a list of integers.

The tclEval(...$args) method allows you to execute arbitrary Tcl commands directly within the application's interpreter. It automatically handles argument quoting for strings and arrays to ensure valid Tcl syntax.

Returns the string result of the evaluated Tcl command.

$result = $app->tclEval('set', 'x', '10');
// or
$result = $app->tclEval('tk', 'windowingsystem');

You can react to users switching between tabs by using the onChanged() method. This method accepts a callback that is executed whenever the selected tab changes.

The callback receives two arguments:

1. The NotebookTab instance that was just selected.
2. The Notebook widget instance.

$notebook->onChanged(function (NotebookTab $tab, Notebook $nb) {
    echo "Selected tab: " . $tab->title(); // Assuming title() exists on NotebookTab
});

$notebook->onChanged(function (NotebookTab $tab, Notebook $nb) {
    // Logic to execute when a tab is selected
});