Skip to content

Commit dfe344c

Browse files
AylurAylur
committed
explain setup and attribute prop #29 
1 parent f2de378 commit dfe344c

File tree

1 file changed

+148
-55
lines changed

1 file changed

+148
-55
lines changed

‎src/content/docs/config/widgets.md

+148-55
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,108 @@ These widgets have some additional properties on top of the base Gtk.Widget ones
1919
| attribute | `any` | Any additional attributes on `self` |
2020
| setup | `(self) => void` | A callback function to execute on `self` |
2121

22+
## Setup property
23+
24+
`setup` is a convenience prop to have imperative code inside declarative blocks
25+
26+
without `setup`
27+
28+
```js
29+
function MyWidget() {
30+
const self = Widget.Button()
31+
// imperative code
32+
return self
33+
}
34+
```
35+
36+
using `setup`
37+
38+
```js
39+
const MyWidget = () => Widget.Button({
40+
setup: self => {
41+
// imperative code
42+
}
43+
})
44+
```
45+
46+
## Attribute property
47+
48+
for attaching additional attributes on widgets `Object.assign` or
49+
the `attribute` property can be used
50+
51+
```js
52+
function MyWidget() {
53+
const self = Widget.Button()
54+
return Object.assign(self, {
55+
myPrimitiveProperty: "anything",
56+
myObjectProperty: {
57+
something: "anything",
58+
key: "value",
59+
},
60+
})
61+
}
62+
63+
const mywidget = MyWidget()
64+
console.log(mywidget.myPrimitiveProperty) // anything
65+
console.log(mywidget.myObjectProperty) // { something: "anything", key: "value" }
66+
```
67+
68+
using `attribute` has the benefit of it being a gobject
69+
which means it will signal `notify::attribute` when it changes
70+
71+
```js
72+
const MyWidget = () => Widget.Button({
73+
attribute: "anything",
74+
setup: self => self.on("notify::attribute", () => {
75+
console.log(mywidget.attribute)
76+
}),
77+
})
78+
79+
const mywidget = MyWidget()
80+
console.log(mywidget.attribute) // anything
81+
82+
// this line will invoke the above console.log in the setup
83+
mywidget.attribute = "something else"
84+
```
85+
86+
keep in mind that `attribute` will only signal if *its value* changes
87+
88+
```js
89+
const MyWidget = () => Widget.Button({
90+
attribute: {
91+
someKey: "value",
92+
key: "value",
93+
},
94+
setup: self => self.on("notify::attribute", () => {
95+
console.log(mywidget.attribute)
96+
})
97+
})
98+
99+
const mywidget = MyWidget()
100+
101+
// this line won't signal, because the attribute is still the same object
102+
mywidget.attribute.key = "new value"
103+
104+
// to have it signal, assign a new object to it
105+
mywidget.attribute = {
106+
...mywidget.attribute,
107+
key: "new value"
108+
}
109+
```
110+
111+
## Common Gtk properties
112+
22113
Some common Gtk.Widget properties you might want for example
23114

24115
| Property | Type | Description |
25116
|----------|------|-------------|
26-
| hexpand | boolean | Expand horizontally. |
27-
| vexpand | boolean | Expand vertically. |
28-
| sensitive | boolean | Makes the widget interactable. |
29-
| tooltip-text | string | Tooltip popup when the widget is hovered over. |
30-
| visible | boolean | Visibility of the widget. Setting this to `false` doesn't have any effect if the parent container calls `show_all()`, for example when you set a Box's children dynamically. |
117+
| hexpand | `boolean` | Expand horizontally. |
118+
| vexpand | `boolean` | Expand vertically. |
119+
| sensitive | `boolean` | Makes the widget interactable. |
120+
| tooltip-text | `string` | Tooltip popup when the widget is hovered over. |
121+
| visible | `boolean` | Visibility of the widget. Setting this to `false` doesn't have any effect if the parent container calls `show_all()`, for example when you set a Box's children dynamically. |
122+
123+
## toggleClassName
31124

32125
If you don't want to mutate the `classNames` array,
33126
there is `toggleClassName`: `(name: string, enable: boolean) => void`
@@ -54,15 +147,15 @@ the toplevel widget that holds everything
54147

55148
| Property | Type | Description |
56149
|----------|------|-------------|
57-
| child | Widget | |
58-
| name | string | Name of the window. This has to be unique, if you pass it in config. This will also be the name of the layer. |
59-
| anchor | string[] | Valid values are `"top"`, `"bottom"`, `"left"`, `"right"`. Anchor points of the window. Leave it empty to make it centered. |
60-
| exclusivity | string | Specify if the compositor should reserve space for the window automatically or how the window should interact with windows that do. Possible values: `exclusive` (space should be reserved), `normal` (the window should move if occluding another), `ignore` (the window should not be moved). Default: `normal`. |
61-
| layer | string | Valid values are `"overlay"`, `"top"`, `"bottom"`, `"background"`. It is `"top"` by default. |
62-
| margins | number[] | Corresponds to CSS notation, e.g `[0, 6]` would have 0 margin on the top and bottom and would have 6 on the right and left. |
63-
| monitor | number | Which monitor to show the window on. If it is left undefined the window will show on the currently focused monitor. |
64-
| keymode | string | Valid values are `"none"`, `"on-demand"`: can receive keyboard input if focused, `"exclusive"`: steal keyboard input on top and overlay layers |
65-
| gdkmonitor | Gdk.Monitor | alternative to `monitor` |
150+
| child | `Widget` | |
151+
| name | `string` | Name of the window. This has to be unique, if you pass it in config. This will also be the name of the layer. |
152+
| anchor | `string[]` | Valid values are `"top"`, `"bottom"`, `"left"`, `"right"`. Anchor points of the window. Leave it empty to make it centered. |
153+
| exclusivity | `string` | Specify if the compositor should reserve space for the window automatically or how the window should interact with windows that do. Possible values: `exclusive` (space should be reserved), `normal` (the window should move if occluding another), `ignore` (the window should not be moved). Default: `normal`. |
154+
| layer | `string` | Valid values are `"overlay"`, `"top"`, `"bottom"`, `"background"`. It is `"top"` by default. |
155+
| margins | `number[]` | Corresponds to CSS notation, e.g `[0, 6]` would have 0 margin on the top and bottom and would have 6 on the right and left. |
156+
| monitor | `number` | Which monitor to show the window on. If it is left undefined the window will show on the currently focused monitor. |
157+
| keymode | `string` | Valid values are `"none"`, `"on-demand"`: can receive keyboard input if focused, `"exclusive"`: steal keyboard input on top and overlay layers |
158+
| gdkmonitor | `Gdk.Monitor` | alternative to `monitor` |
66159

67160
```js
68161
const window = Widget.Window({
@@ -85,8 +178,8 @@ the main container widget
85178

86179
| Property | Type | Description |
87180
|----------|------|-------------|
88-
| vertical | bool | setting `vertical: true` is the same as `orientation: 1` |
89-
| children | Widget[] | List of child widgets. |
181+
| vertical | `bool` | setting `vertical: true` is the same as `orientation: 1` |
182+
| children | `Widget[]` | List of child widgets. |
90183

91184
```js
92185
const box = Widget.Box({
@@ -107,7 +200,7 @@ subclass of [Gtk.Button](https://gjs-docs.gnome.org/gtk30~3.0/gtk.button)
107200

108201
| Property | Type |
109202
|----------|------|
110-
| child | Widget |
203+
| child | `Widget` |
111204
| on-clicked | `() => void` |
112205
| on-primary-click | `(event: Gdk.Event) => boolean` |
113206
| on-secondary-click | `(event: Gdk.Event) => boolean` |
@@ -154,14 +247,14 @@ const calendar = Widget.Calendar({
154247

155248
### CenterBox
156249

157-
subclass of Box
250+
subclass of [Gtk.Box](https://gjs-docs.gnome.org/gtk30~3.0/gtk.box)
158251

159252
| Property | Type | Description |
160253
|----------|------|-------------|
161-
| vertical | bool | setting `vertical: true` is the same as `orientation: 1` |
162-
| start-widget | Gtk.Widget | |
163-
| center-widget | Gtk.Widget | |
164-
| end-widget | Gtk.Widget | |
254+
| vertical | `bool` | setting `vertical: true` is the same as `orientation: 1` |
255+
| start-widget | `Gtk.Widget` | |
256+
| center-widget | `Gtk.Widget` | |
257+
| end-widget | `Gtk.Widget` | |
165258

166259
```js
167260
const centerBox = Widget.CenterBox({
@@ -179,11 +272,11 @@ subclass of [Gtk.Bin](https://gjs-docs.gnome.org/gtk30~3.0/gtk.bin)
179272

180273
| Property | Type | Description |
181274
|----------|------|-------------|
182-
| start-at | number | Number between 0 and 1, e.g 0.75 is the top |
183-
| end-at | number | Number between 0 and 1 |
184-
| inverted | boolean | |
185-
| rounded | boolean | Wether the progress bar should have rounded ends |
186-
| value | number | Number between 0 and 1 |
275+
| start-at | `number` | Number between 0 and 1, e.g 0.75 is the top |
276+
| end-at | `number` | Number between 0 and 1 |
277+
| inverted | `boolean` | |
278+
| rounded | `boolean` | Wether the progress bar should have rounded ends |
279+
| value | `number` | Number between 0 and 1 |
187280

188281
```js
189282
const progress = Widget.CircularProgress({
@@ -269,7 +362,7 @@ subclass of [Gtk.EventBox](https://gjs-docs.gnome.org/gtk30~3.0/gtk.eventbox)
269362

270363
| Property | Type |
271364
|----------|------|
272-
| child | Widget |
365+
| child | `Widget` |
273366
| on-primary-click | `(event: Gdk.Event) => boolean` |
274367
| on-secondary-click | `(event: Gdk.Event) => boolean` |
275368
| on-middle-click | `(event: Gdk.Event) => boolean` |
@@ -356,8 +449,8 @@ subclass of [Gtk.Image](https://gjs-docs.gnome.org/gtk30~3.0/gtk.image)
356449

357450
| Property | Type | Description |
358451
|----------|------|-------------|
359-
| icon | string | Name of an icon or path to a file |
360-
| size | number | Forced size |
452+
| icon | `string` | Name of an icon or path to a file |
453+
| size | `number` | Forced size |
361454

362455
```js
363456
Widget.Icon({ icon: 'dialog-information-symbolic' })
@@ -386,8 +479,8 @@ subclass of [Gtk.Label](https://gjs-docs.gnome.org/gtk30~3.0/gtk.label)
386479

387480
| Property | Type | Description |
388481
|----------|------|-------------|
389-
| justification | string | Valid values are `"left"`, `"center"`, `"right"`, `"fill"`. Same as `justify` but represented as a string instead of enum. |
390-
| truncate | string | Valid values are `"none"`, `"start"`, `"middle"`, `"end"`. Same as `ellipsize` but represented as a string instead of enum. |
482+
| justification | `string` | Valid values are `"left"`, `"center"`, `"right"`, `"fill"`. Same as `justify` but represented as a string instead of enum. |
483+
| truncate | `string` | Valid values are `"none"`, `"start"`, `"middle"`, `"end"`. Same as `ellipsize` but represented as a string instead of enum. |
391484

392485
```js
393486
const label = Widget.Label({
@@ -410,8 +503,8 @@ subclass of [Gtk.LevelBar](https://gjs-docs.gnome.org/gtk30~3.0/gtk.levelbar)
410503

411504
| Property | Type | Description |
412505
|----------|------|-------------|
413-
| bar-mode | string | Valid values are `"continuous"`, `"discrete"`. Same as `mode` but represented as a string instead of enum. |
414-
| vertical | bool | setting `vertical: true` is the same as `orientation: 1` |
506+
| bar-mode | `string` | Valid values are `"continuous"`, `"discrete"`. Same as `mode` but represented as a string instead of enum. |
507+
| vertical | `bool` | setting `vertical: true` is the same as `orientation: 1` |
415508

416509
```js
417510
const continuous = Widget.LevelBar({
@@ -450,7 +543,7 @@ subclass of [Gtk.Menu](https://gjs-docs.gnome.org/gtk30~3.0/gtk.menu)
450543

451544
| Property | Type |
452545
|----------|------|
453-
| children | MenuItem[] |
546+
| children | `MenuItem[]` |
454547
| on-popup | `(flipped_rect: void, final_rect: void, flipped_x: boolean, flipped_y: boolean) => void` |
455548
| on-move-scroll | `(scroll_type: Gtk.ScrollType) => void` |
456549

@@ -495,7 +588,7 @@ subclass of [Gtk.MenuItem](https://gjs-docs.gnome.org/gtk30~3.0/gtk.menuitem)
495588

496589
| Property | Type |
497590
|----------|------|
498-
| child | Widget |
591+
| child | `Widget` |
499592
| on-activate | `() => boolean` |
500593
| on-select | `() => boolean` |
501594
| on-deselect | `() => boolean` |
@@ -521,9 +614,9 @@ top of each other and won't render them outside the container.
521614

522615
| Property | Type | Description|
523616
|----------|------|------------|
524-
| child | Widget | Child which will determine the size of the overlay |
525-
| overlays | Widget[] | Overlayed children |
526-
| pass-through | boolean | Whether the overlay childs should pass the input through |
617+
| child | `Widget` | Child which will determine the size of the overlay |
618+
| overlays | `Widget[]` | Overlayed children |
619+
| pass-through | `boolean` | Whether the overlay childs should pass the input through |
527620

528621
### ProgressBar
529622

@@ -535,8 +628,8 @@ You might want to use `LevelBar` instead.
535628

536629
| Property | Type | Description |
537630
|----------|------|-------------|
538-
| vertical | bool | Setting `vertical: true` is the same as `orientation: 1` |
539-
| value | number | Same as `ProgressBar.fraction` |
631+
| vertical | `bool` | Setting `vertical: true` is the same as `orientation: 1` |
632+
| value | `number` | Same as `ProgressBar.fraction` |
540633

541634
```js
542635
const progressbar = Widget.ProgressBar({
@@ -550,8 +643,8 @@ subclass of [Gtk.Revealer](https://gjs-docs.gnome.org/gtk30~3.0/gtk.revealer)
550643

551644
| Property | Type | Description |
552645
|----------|------|-------------|
553-
| child | Widget | |
554-
| transition | string | Valid values are `"none"`, `"crossfade"`, `"slide_left"`, `"slide_right"`, `"slide_down"`, `"slide_up"`. This is `transitionType` represented as a string instead of enum. |
646+
| child | `Widget` | |
647+
| transition | `string` | Valid values are `"none"`, `"crossfade"`, `"slide_left"`, `"slide_right"`, `"slide_down"`, `"slide_up"`. This is `transitionType` represented as a string instead of enum. |
555648

556649
```js
557650
const revealer = Widget.Revealer({
@@ -571,9 +664,9 @@ subclass of [Gtk.ScrolledWindow](https://gjs-docs.gnome.org/gtk30~3.0/gtk.scroll
571664

572665
| Property | Type | Description |
573666
|----------|------|-------------|
574-
| child | Widget | |
575-
| hscroll | string | Valid values are `"always`, `"automatic"`, `"external"`, `"never"`. |
576-
| vscroll | string | Valid values are `"always`, `"automatic"`, `"external"`, `"never"`. |
667+
| child | `Widget` | |
668+
| hscroll | `string` | Valid values are `"always`, `"automatic"`, `"external"`, `"never"`. |
669+
| vscroll | `string` | Valid values are `"always`, `"automatic"`, `"external"`, `"never"`. |
577670

578671
```js
579672
const scrollable = Widget.Scrollable({
@@ -592,7 +685,7 @@ subclass of [Gtk.Separator](https://gjs-docs.gnome.org/gtk30~3.0/gtk.separator)
592685

593686
| Property | Type | Description |
594687
|----------|------|-------------|
595-
| vertical | bool | Setting `vertical: true` is the same as `orientation: 1` |
688+
| vertical | `bool` | Setting `vertical: true` is the same as `orientation: 1` |
596689

597690
```js
598691
const separator = Widget.Separator({
@@ -606,11 +699,11 @@ subclass of [Gtk.Scale](https://gjs-docs.gnome.org/gtk30~3.0/gtk.scale)
606699

607700
| Property | Type | Description |
608701
|----------|------|-------------|
609-
| vertical | bool | Setting `vertical: true` is the same as `orientation: 1` |
610-
| value | number | |
611-
| min | number | |
612-
| max | number | |
613-
| marks | tuple or number | where tuple is [number, string?, Position?], Position is `"top"`, `"left`, `"right`, `"bottom"` |
702+
| vertical | `bool` | Setting `vertical: true` is the same as `orientation: 1` |
703+
| value | `number` | |
704+
| min | `number` | |
705+
| max | `number` | |
706+
| marks | `tuple` or `number` | where tuple is `[number, string?, Position?]`, Position is `"top"`, `"left`, `"right`, `"bottom"` |
614707
| on-change | `(event: Gdk.Event) => void` | |
615708

616709
```js
@@ -664,9 +757,9 @@ subclass of [Gtk.Stack](https://gjs-docs.gnome.org/gtk30~3.0/gtk.stack)
664757

665758
| Property | Type | Description |
666759
|----------|------|-------------|
667-
| children | \{string, Widget\} | name: Widget key-value pairs |
668-
| shown | string | Name of the widget to show. This can't be set on construction, instead the first given widget will be shown. |
669-
| transition | string | `transitionType` represented as a string. Valid values are `none`, `crossfade`, `slide_right`, `slide_left`, `slide_up`, `slide_down`, `slide_left_right`, `slide_up_down`, `over_up`, `over_down`, `over_left`, `over_right`, `under_up`, `under_down`, `under_left`, `under_right`, `over_up_down`, `over_down_up`, `over_left_right`, `over_right_left`
760+
| children | `{ [string]: Widget }` | name, Widget key-value pairs |
761+
| shown | `string` | Name of the widget to show. This can't be set on construction, instead the first given widget will be shown. |
762+
| transition | `string` | `transitionType` represented as a string. Valid values are `none`, `crossfade`, `slide_right`, `slide_left`, `slide_up`, `slide_down`, `slide_left_right`, `slide_up_down`, `over_up`, `over_down`, `over_left`, `over_right`, `under_up`, `under_down`, `under_left`, `under_right`, `over_up_down`, `over_down_up`, `over_left_right`, `over_right_left`
670763

671764
```js
672765
const stack = Widget.Stack({

0 commit comments

Comments
 (0)