Skip to content

Commit 372d781

Browse files
developersharifdevelopersharif
authored
Merge pull request #14 from developersharif/docv1.5
docs: standardize and expand documentation for all widgets with constructors, methods, and examples.
2 parents 7ef0f70 + 4e684fd commit 372d781

15 files changed

Lines changed: 1049 additions & 96 deletions

‎docs/Button.md‎

Lines changed: 81 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,90 @@
11
# Button Widget
22

3-
The **Button** widget triggers actions when clicked.
3+
The **Button** widget renders a clickable button and executes a PHP callback when clicked. It extends `AbstractWidget`, so it inherits `pack()`, `place()`, `grid()`, and `destroy()`.
44

5-
### Example
5+
---
6+
7+
### Constructor
8+
9+
```php
10+
new Button(string $parentId, array $options = [])
11+
```
12+
13+
| Parameter | Type | Description |
14+
|------------|----------|-----------------------------------------------------|
15+
| `$parentId`| `string` | The `getId()` result of the parent widget (e.g. `Window`) |
16+
| `$options` | `array` | Configuration options — see table below |
17+
18+
---
19+
20+
### Options
21+
22+
| Key | Type | Description |
23+
|-----------|------------|----------------------------------------------------------------|
24+
| `text` | `string` | Label shown on the button. Defaults to `'Button'`. |
25+
| `command` | `callable` | PHP closure called when the button is clicked. |
26+
| `bg` | `string` | Background color (name or hex, e.g. `'blue'`, `'#ff0000'`). |
27+
| `fg` | `string` | Foreground (text) color. |
28+
| `font` | `string` | Font string, e.g. `'Helvetica 16 bold'`. |
29+
| `relief` | `string` | Border style: `flat`, `raised`, `sunken`, `groove`, `ridge`. |
30+
| `padx` | `int` | Horizontal internal padding in pixels. |
31+
| `pady` | `int` | Vertical internal padding in pixels. |
32+
33+
Any option other than `text` and `command` is passed directly to the underlying Tk `button` command.
34+
35+
---
36+
37+
### Examples
38+
39+
**Basic button:**
640
```php
741
use PhpGui\Widget\Button;
8-
$button = new Button('parentId', [
9-
'text' => 'Submit',
10-
'command' => function() {
11-
echo "Button clicked!";
42+
43+
$btn = new Button($window->getId(), [
44+
'text' => 'Click Me',
45+
'command' => function () {
46+
echo "Button clicked!\n";
1247
}
1348
]);
49+
$btn->pack(['pady' => 10]);
50+
```
51+
52+
**Styled button with custom colors and font:**
53+
```php
54+
$styledButton = new Button($window->getId(), [
55+
'text' => 'Styled Button',
56+
'command' => function () use ($label) {
57+
$label->setText('Styled Button clicked!');
58+
},
59+
'bg' => 'blue',
60+
'fg' => 'white',
61+
'font' => 'Helvetica 16 bold'
62+
]);
63+
$styledButton->pack(['pady' => 10]);
64+
```
65+
66+
**Button without a callback (display-only):**
67+
```php
68+
$btn = new Button($window->getId(), ['text' => 'No Action']);
69+
$btn->pack();
70+
```
71+
72+
---
73+
74+
### Layout
75+
76+
All three geometry managers are supported (inherited from `AbstractWidget`):
77+
78+
```php
79+
$btn->pack(['side' => 'left', 'padx' => 5]);
80+
$btn->place(['x' => 100, 'y' => 50]);
81+
$btn->grid(['row' => 0, 'column' => 1]);
1482
```
1583

16-
### Details
17-
- Can be customized with additional options (e.g., bg, fg, font).
18-
- Registers a PHP callback to handle click events.
19-
- Essential for interactive actions in a GUI.
84+
---
85+
86+
### Notes
87+
88+
- The `command` option is extracted from `$options` and registered via `ProcessTCL::registerCallback()`. The PHP closure is invoked each time the button is clicked, then `update` is called to force widget refresh.
89+
- All other keys in `$options` are forwarded as Tk options using `-key "value"` formatting.
90+
- `destroy()` removes the button from the Tk interpreter immediately.

‎docs/Canvas.md‎

Lines changed: 86 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,94 @@
11
# Canvas Widget
22

3-
The **Canvas** widget provides a drawing area for graphics, shapes, and custom rendering.
3+
The **Canvas** widget provides a 2D drawing area where you can programmatically render lines, rectangles, ovals, and text. Every draw method returns a Tk item ID (as a `string`) that can be used to delete specific items later.
4+
5+
---
6+
7+
### Constructor
8+
9+
```php
10+
new Canvas(string $parentId, array $options = [])
11+
```
12+
13+
| Parameter | Type | Description |
14+
|-------------|----------|------------------------------------------|
15+
| `$parentId` | `string` | `getId()` of the parent widget. |
16+
| `$options` | `array` | Configuration options — see table below. |
17+
18+
---
19+
20+
### Options
21+
22+
| Key | Type | Description |
23+
|----------|----------|------------------------------------|
24+
| `width` | `int` | Canvas width in pixels. |
25+
| `height` | `int` | Canvas height in pixels. |
26+
| `bg` | `string` | Background color of the canvas. |
27+
28+
All options are forwarded directly to the Tk `canvas` command.
29+
30+
---
431

532
### Example
33+
634
```php
735
use PhpGui\Widget\Canvas;
8-
$canvas = new Canvas('parentId');
36+
37+
$canvas = new Canvas($window->getId(), [
38+
'width' => 400,
39+
'height' => 300,
40+
'bg' => 'white'
41+
]);
42+
$canvas->pack(['pady' => 10]);
43+
44+
// Draw shapes
45+
$lineId = $canvas->drawLine(10, 10, 200, 10, ['fill' => 'black', 'width' => 2]);
46+
$rectId = $canvas->drawRectangle(50, 50, 200, 150, ['fill' => 'lightblue', 'outline' => 'navy']);
47+
$ovalId = $canvas->drawOval(220, 50, 370, 150, ['fill' => 'salmon']);
48+
$textId = $canvas->drawText(100, 180, 'Hello Canvas', ['fill' => 'darkgreen', 'font' => 'Arial 14 bold']);
49+
50+
// Delete a specific item by its returned ID
51+
$canvas->delete($rectId);
52+
53+
// Clear the entire canvas
54+
$canvas->clear();
955
```
1056

11-
### Details
12-
- Typically used for custom drawings.
13-
- Can be modified using additional Tcl commands.
14-
- Offers a flexible area for graphical content.
57+
---
58+
59+
### Methods
60+
61+
| Method | Signature | Returns | Description |
62+
|---------------------|----------------------------------------------------------------------|----------|---------------------------------------------------------------|
63+
| `drawLine()` | `(int $x1, int $y1, int $x2, int $y2, array $options = []): string` | item ID | Draws a line between two points. |
64+
| `drawRectangle()` | `(int $x1, int $y1, int $x2, int $y2, array $options = []): string` | item ID | Draws a rectangle from top-left to bottom-right. |
65+
| `drawOval()` | `(int $x1, int $y1, int $x2, int $y2, array $options = []): string` | item ID | Draws an oval/ellipse bounded by the given rectangle. |
66+
| `drawText()` | `(int $x, int $y, string $text, array $options = []): string` | item ID | Draws text anchored at the given coordinates. |
67+
| `delete()` | `(string $itemId): void` | — | Deletes a single item by the ID returned from a draw method. |
68+
| `clear()` | `(): void` | — | Deletes all items on the canvas (`delete all`). |
69+
| `pack()` | `(array $opts = []): void` | — | Inherited. Pack layout manager. |
70+
| `place()` | `(array $opts = []): void` | — | Inherited. Place layout manager. |
71+
| `grid()` | `(array $opts = []): void` | — | Inherited. Grid layout manager. |
72+
| `destroy()` | `(): void` | — | Inherited. Removes the canvas widget. |
73+
74+
---
75+
76+
### Draw Options Reference
77+
78+
Options arrays for draw methods accept standard Tk item configuration keys:
79+
80+
| Key | Applicable to | Description |
81+
|-----------|-----------------------|------------------------------------|
82+
| `fill` | all shapes, text | Fill color. |
83+
| `outline` | rectangle, oval | Border color. |
84+
| `width` | line, rectangle, oval | Border/stroke width in pixels. |
85+
| `font` | text | Font string, e.g. `'Arial 14 bold'`.|
86+
| `anchor` | text | Anchor point: `center`, `nw`, etc. |
87+
88+
---
89+
90+
### Notes
91+
92+
- `drawText()` uses `-text {text}` so the text string is passed as a Tk list element — it can contain spaces.
93+
- All coordinate values are in pixels, measured from the top-left corner of the canvas.
94+
- `Canvas` overrides `formatOptions()` from `AbstractWidget` to produce `-key value` without wrapping values in quotes (important for numeric coordinates).

‎docs/Checkbutton.md‎

Lines changed: 78 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,85 @@
11
# Checkbutton Widget
22

3-
The **Checkbutton** widget is used for boolean toggle inputs.
3+
The **Checkbutton** widget renders a labelled checkbox. It uses a Tk `checkbutton` linked to an internal Tcl variable (`cb_var_{id}`) so the checked state is always readable and writable from PHP.
4+
5+
---
6+
7+
### Constructor
48

5-
### Example
9+
```php
10+
new Checkbutton(string $parentId, array $options = [])
11+
```
12+
13+
| Parameter | Type | Description |
14+
|-------------|----------|------------------------------------------|
15+
| `$parentId` | `string` | `getId()` of the parent widget. |
16+
| `$options` | `array` | Configuration options — see table below. |
17+
18+
---
19+
20+
### Options
21+
22+
| Key | Type | Description |
23+
|-----------|------------|--------------------------------------------------------------------------|
24+
| `text` | `string` | Label shown next to the checkbox. Defaults to `'Checkbutton'`. |
25+
| `command` | `callable` | PHP closure called each time the checkbox is toggled. |
26+
| `bg` | `string` | Background color. |
27+
| `fg` | `string` | Foreground (text) color. |
28+
| `font` | `string` | Font string, e.g. `'Arial 12'`. |
29+
30+
Options other than `text` and `command` are forwarded as Tk `-key "value"` pairs.
31+
32+
---
33+
34+
### Examples
35+
36+
**Basic checkbox:**
637
```php
738
use PhpGui\Widget\Checkbutton;
8-
$check = new Checkbutton('parentId', ['text' => 'Check me']);
9-
$check->setChecked(true);
39+
40+
$check = new Checkbutton($window->getId(), ['text' => 'Accept Terms']);
41+
$check->pack(['pady' => 5]);
42+
43+
// Read state
44+
echo $check->isChecked() ? 'Checked' : 'Unchecked';
45+
```
46+
47+
**Checkbox with toggle callback:**
48+
```php
49+
$check = new Checkbutton($window->getId(), [
50+
'text' => 'Enable notifications',
51+
'command' => function () use ($check) {
52+
echo $check->isChecked() ? "ON\n" : "OFF\n";
53+
}
54+
]);
55+
$check->pack(['pady' => 5]);
56+
```
57+
58+
**Setting state programmatically:**
59+
```php
60+
$check->setChecked(true); // check it
61+
$check->setChecked(false); // uncheck it
62+
$check->toggle(); // flip current state
1063
```
1164

12-
### Details
13-
- Stores a boolean value (checked or unchecked).
14-
- Provides methods to get and set its state.
15-
- Ideal for forms and settings interfaces.
65+
---
66+
67+
### Methods
68+
69+
| Method | Signature | Description |
70+
|-----------------|-------------------------|---------------------------------------------------------|
71+
| `setChecked()` | `(bool $state): void` | Sets the internal Tcl variable to `1` (true) or `0` (false). |
72+
| `isChecked()` | `(): bool` | Reads the internal Tcl variable and returns `true`/`false`. |
73+
| `toggle()` | `(): void` | Calls `setChecked(!isChecked())` to flip the current state. |
74+
| `pack()` | `(array $opts): void` | Inherited. Pack layout manager. |
75+
| `place()` | `(array $opts): void` | Inherited. Place layout manager. |
76+
| `grid()` | `(array $opts): void` | Inherited. Grid layout manager. |
77+
| `destroy()` | `(): void` | Inherited. Removes the widget. |
78+
79+
---
80+
81+
### Notes
82+
83+
- The internal Tcl variable is initialised to `0` on creation.
84+
- The `command` closure is registered via `ProcessTCL::registerCallback()` and fired via `php::executeCallback` from the Tk side.
85+
- Unlike `Button`, the callback for `Checkbutton` is **not** followed by an `update` call — the Tcl variable change itself triggers the visual update.

‎docs/Combobox.md‎

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,64 @@
11
# Combobox Widget
22

3-
The **Combobox** widget creates a dropdown selection box with a list of options.
3+
The **Combobox** widget renders a `ttk::combobox` — a dropdown list combined with a text field. The list values are space-separated and bound to a Tcl variable so `getValue()` and `setValue()` always reflect the live selection.
4+
5+
---
6+
7+
### Constructor
8+
9+
```php
10+
new Combobox(string $parentId, array $options = [])
11+
```
12+
13+
| Parameter | Type | Description |
14+
|-------------|----------|------------------------------------------|
15+
| `$parentId` | `string` | `getId()` of the parent widget. |
16+
| `$options` | `array` | Configuration options — see table below. |
17+
18+
---
19+
20+
### Options
21+
22+
| Key | Type | Description |
23+
|----------|----------|--------------------------------------------------------------------------------------|
24+
| `values` | `string` | **Space-separated** list of items shown in the dropdown. Defaults to `''` (empty). |
25+
26+
---
427

528
### Example
29+
630
```php
731
use PhpGui\Widget\Combobox;
8-
$combo = new Combobox('parentId', ['values' => 'Option1 Option2 Option3']);
32+
33+
$combo = new Combobox($window->getId(), [
34+
'values' => 'Option1 Option2 Option3'
35+
]);
36+
$combo->pack(['pady' => 10]);
37+
38+
// Read the currently selected / typed value
39+
$selected = $combo->getValue();
40+
41+
// Pre-select a value programmatically
42+
$combo->setValue('Option2');
943
```
1044

11-
### Details
12-
- Uses space-separated values to generate the option list.
13-
- Provides methods to get or set the selected value.
14-
- Great for selection lists and forms.
45+
---
46+
47+
### Methods
48+
49+
| Method | Signature | Description |
50+
|--------------|------------------------|-----------------------------------------------------------------------|
51+
| `getValue()` | `(): string` | Returns the current value via `ProcessTCL::getVar($id)`. |
52+
| `setValue()` | `(string $value): void`| Sets the bound Tcl variable, updating both the text field and dropdown selection. |
53+
| `pack()` | `(array $opts): void` | Inherited. Pack layout manager. |
54+
| `place()` | `(array $opts): void` | Inherited. Place layout manager. |
55+
| `grid()` | `(array $opts): void` | Inherited. Grid layout manager. |
56+
| `destroy()` | `(): void` | Inherited. Removes the widget. |
57+
58+
---
59+
60+
### Notes
61+
62+
- The `values` string is passed directly as a Tcl list `{Option1 Option2 Option3}`. Each space separates an item. If an option contains spaces, you must wrap it in curly braces within the string (e.g. `'{First Item} {Second Item}'`).
63+
- The combobox uses `ttk::combobox`, which is part of the themed Tk widgets (available in Tk 8.5+). No separate `package require` is needed beyond `package require Tk`.
64+
- The `-textvariable` is the widget's unique ID, so `getValue()` simply reads that variable.

0 commit comments

Comments
 (0)