0
# Groovy Swing Builder
1

2
Groovy Swing Builder is a declarative GUI builder for Groovy applications that provides a concise and maintainable way to create complex Swing user interfaces. It leverages Groovy's builder pattern and metaprogramming capabilities to dramatically reduce the boilerplate code typically associated with Swing development while maintaining full access to the complete Swing component ecosystem.
3

4
## Package Information
5

6
- **Package Name**: groovy-swing
7
- **Package Type**: maven
8
- **Group ID**: org.codehaus.groovy
9
- **Language**: Groovy/Java
10
- **Installation**: 
11

12
**Maven:**
13
```xml
14
<dependency>
15
    <groupId>org.codehaus.groovy</groupId>
16
    <artifactId>groovy-swing</artifactId>
17
    <version>3.0.25</version>
18
</dependency>
19
```
20

21
**Gradle:**
22
```groovy
23
implementation 'org.codehaus.groovy:groovy-swing:3.0.25'
24
```
25

26
## Core Imports
27

28
```groovy
29
import groovy.swing.SwingBuilder
30
import groovy.swing.LookAndFeelHelper
31
```
32

33
For specific factory classes:
34
```groovy
35
import groovy.swing.factory.*
36
import groovy.swing.binding.*
37
import groovy.model.*
38
```
39

40
## Basic Usage
41

42
```groovy
43
import groovy.swing.SwingBuilder
44
import javax.swing.*
45

46
// Create a simple GUI using SwingBuilder
47
def swing = new SwingBuilder()
48
def frame = swing.frame(title: 'Hello Groovy Swing', defaultCloseOperation: JFrame.EXIT_ON_CLOSE) {
49
    panel {
50
        label(text: 'Hello, World!')
51
        button(text: 'Click Me') {
52
            actionPerformed { e ->
53
                JOptionPane.showMessageDialog(null, 'Button clicked!')
54
            }
55
        }
56
    }
57
}
58
frame.pack()
59
frame.visible = true
60

61
// Using EDT builder for thread safety
62
SwingBuilder.edtBuilder {
63
    frame(title: 'EDT Example', defaultCloseOperation: JFrame.EXIT_ON_CLOSE) {
64
        textField(text: 'Type here...', columns: 20)
65
    }.show()
66
}
67
```
68

69
## Architecture
70

71
Groovy Swing Builder is built around several key components:
72

73
- **SwingBuilder**: Central orchestrator providing the builder DSL and component factories
74
- **Factory System**: 60+ specialized factories for creating and configuring Swing components
75
- **Binding System**: Comprehensive data binding framework for MVC architecture
76
- **Model Integration**: Value models for clean separation of data and presentation
77
- **Layout Management**: Enhanced layout managers including custom table-based layouts
78
- **Threading Utilities**: EDT-safe methods for proper Swing thread management
79
- **Extension System**: Groovy-specific enhancements to standard Swing components
80

81
## Capabilities
82

83
### Core GUI Building
84

85
The primary SwingBuilder class and factory system for declarative GUI construction with the builder pattern.
86

87
```groovy { .api }
88
class SwingBuilder extends FactoryBuilderSupport {
89
    static final String DELEGATE_PROPERTY_OBJECT_ID = "_delegateProperty:id"
90
    static final String DEFAULT_DELEGATE_PROPERTY_OBJECT_ID = "id"
91
    
92
    SwingBuilder(boolean init = true)
93
    SwingBuilder edt(Closure c)
94
    SwingBuilder doLater(Closure c)
95
    SwingBuilder doOutside(Closure c)
96
    Object build(Closure c)
97
    KeyStroke shortcut(key, modifier = 0)
98
    KeyStroke shortcut(String key, modifier = 0)
99
    void createKeyStrokeAction(Map attributes, JComponent component = null)
100
    static SwingBuilder edtBuilder(Closure c)
101
    static LookAndFeel lookAndFeel(Object... lafs)
102
    static LookAndFeel lookAndFeel(Object laf, Closure initCode)
103
    static LookAndFeel lookAndFeel(Map attributes, Object laf, Closure initCode)
104
}
105
```
106

107
[GUI Building and Components](./gui-building.md)
108

109
### Data Binding
110

111
Sophisticated binding system for connecting GUI components to data models with validation, conversion, and automatic synchronization.
112

113
```groovy { .api }
114
interface FullBinding extends BindingUpdatable {
115
    SourceBinding getSourceBinding()
116
    TargetBinding getTargetBinding()
117
    void setSourceBinding(SourceBinding source)
118
    void setTargetBinding(TargetBinding target)
119
    void setValidator(Closure validator)
120
    void setConverter(Closure converter)
121
    void setReverseConverter(Closure reverseConverter)
122
}
123

124
interface ValueModel {
125
    Object getValue()
126
    void setValue(Object value)
127
    Class getType()
128
    boolean isEditable()
129
}
130
```
131

132
[Data Binding System](./data-binding.md)
133

134
### Layout Management
135

136
Comprehensive layout system including all standard Swing layouts plus custom table-based layout manager.
137

138
```groovy { .api }
139
// Standard layouts via LayoutFactory
140
borderLayout(hgap: 5, vgap: 5)
141
gridLayout(rows: 2, cols: 3, hgap: 5, vgap: 5)
142
flowLayout(alignment: FlowLayout.CENTER)
143

144
// Enhanced GridBag with constraint handling
145
gridBagLayout()
146
gridBagConstraints(gridx: 0, gridy: 0, weightx: 1.0)
147

148
// Custom table layout
149
tableLayout {
150
    tr {
151
        td { button(text: 'Button 1') }
152
        td { button(text: 'Button 2') }
153
    }
154
}
155
```
156

157
[Layout Management](./layout-management.md)
158

159
### Look and Feel
160

161
Simplified Look and Feel management with support for system LAFs and third-party themes.
162

163
```groovy { .api }
164
class LookAndFeelHelper {
165
    static LookAndFeelHelper getInstance()
166
    LookAndFeel lookAndFeel(Object value, Map attributes, Closure initClosure)
167
    String addLookAndFeelAlias(String alias, String className)
168
    String addLookAndFeelAttributeHandler(String className, String attr, Closure handler)
169
}
170
```
171

172
[Look and Feel Management](./look-and-feel.md)
173

174
### Swing Extensions
175

176
Groovy-specific enhancements to standard Swing components providing collection-like operators and convenient methods.
177

178
```groovy { .api }
179
// Collection-like operations for containers
180
panel << button  // Add component using left-shift
181
button = panel[0]  // Access by index
182
panel.size()  // Get component count
183
panel.each { ... }  // Iterate over components
184

185
// Enhanced operations for various components
186
listModel << 'item'  // Add to list model
187
comboBox << 'option'  // Add to combo box
188
buttonGroup << radioButton  // Add to button group
189
```
190

191
[Swing Extensions](./extensions.md)
192

193
### Value Models and Data Models
194

195
Observable data containers and specialized models supporting property change notifications and data binding integration.
196

197
```groovy { .api }
198
interface ValueModel {
199
    Object getValue()
200
    void setValue(Object value)
201
    Class getType()
202
    boolean isEditable()
203
}
204

205
class ValueHolder implements ValueModel {
206
    ValueHolder(Object value = null)
207
}
208

209
class PropertyModel implements ValueModel {
210
    PropertyModel(Object bean, String property)
211
}
212

213
class FormModel implements ValueModel {
214
    FormModel(Map initialData = [:])
215
    boolean isDirty()
216
    Map<String, List<String>> validate()
217
}
218
```
219

220
[Value Models and Data Models](./models.md)
221

222
## Types
223

224
### Core Builder Types
225

226
```groovy { .api }
227
abstract class FactoryBuilderSupport {
228
    protected Map<String, Factory> factories
229
    protected Object current
230
    protected LinkedList<Object> contexts
231
    
232
    void registerFactory(String name, Factory factory)
233
    Object build(Closure c)
234
    Object getCurrent()
235
}
236

237
interface Factory {
238
    Object newInstance(FactoryBuilderSupport builder, Object name, Object value, Map attributes)
239
    boolean isLeaf()
240
    boolean onHandleNodeAttributes(FactoryBuilderSupport builder, Object node, Map attributes)
241
    void onNodeCompleted(FactoryBuilderSupport builder, Object parent, Object node)
242
}
243
```
244

245
### Binding Types
246

247
```groovy { .api }
248
interface BindingUpdatable {
249
    void bind()
250
    void unbind()
251
    void rebind()
252
    void update()
253
    void reverseUpdate()
254
}
255

256
interface SourceBinding extends BindingUpdatable {
257
    Object getSourceValue()
258
    void setSourceBinding(PropertyChangeListener listener)
259
}
260

261
interface TargetBinding extends BindingUpdatable {
262
    void setTargetValue(Object value)
263
}
264

265
interface TriggerBinding {
266
    FullBinding getFullBinding()
267
    void setFullBinding(FullBinding fullBinding)
268
    void bind()
269
    void unbind()
270
}
271
```
272

273
### Component Property Types
274

275
```groovy { .api }
276
// Text component bindings
277
interface JTextComponentProperties {
278
    Object getText(JTextComponent self)
279
    void setText(JTextComponent self, Object value)
280
}
281

282
// Button state bindings  
283
interface AbstractButtonProperties {
284
    Object getSelected(AbstractButton self)
285
    void setSelected(AbstractButton self, Object value)
286
}
287

288
// Selection model bindings
289
interface JListProperties {
290
    Object getSelectedElement(JList self)
291
    Object getSelectedElements(JList self)
292
    Object getSelectedIndex(JList self)
293
    Object getSelectedIndices(JList self)
294
    Object getSelectedValue(JList self)
295
    Object getSelectedValues(JList self)
296
}
297
```