~ubuntu-branches/ubuntu/utopic/java-gnome/utopic : revision 17

1

NEWS

2

3

4

5

java-gnome 4.1.2 (30 Aug 2012)

6

===============================

7

8

_Applications don't stand idly by._

9

10

After a bit of a break, we're back with a second release in the 4.1 series

11

covering GNOME 3 and its libraries.

12

13

Application for Unique

14

----------------------

15

16

The significant change in this release is the introduction of GtkApplication,

17

the new mechanism providing for unique instances of applications. This

18

replaces the use of libunique for this purpose, which GNOME has deprecated and

19

asked us to remove.

20

21

* **`org.gnome.gtk.Application`**

22

* **`org.gnome.glib.Application`**

23

* **`org.gnome.glib.ApplicationFlags`**

24

* **`org.gnome.glib.ApplicationCommandLine`**

25

* <strike>`org.gnome.unique.Application`</strike>

26

* <strike>`org.gnome.unique.Message`</strike>

27

* <strike>`org.gnome.unique.Response`</strike>

28

29

Thanks to Guillaume Mazoyer for having done the grunt work figuring out how

30

the underlying GApplication mechanism worked.

31

32

Idle time

33

---------

34

35

The new Application coverage doesn't work with java-gnome's multi-thread

36

safety because GTK itself is not going to be thread safe anymore. This is a

37

huge step backward, but has been coming for a while, and despite our intense

38

disappointment about it all, java-gnome will now be like every other GUI

39

toolkit out there: not thread safe.

40

41

If you're working from another thread and need to update your GTK widgets, you

42

must do so from within the main loop. To get there, you add an idle handler

43

which will get a callback from the main thread at some future point. We've

44

exposed that as `Glib.idleAdd()`; you put your call back in an instance of the

45

Handler interface.

46

47

* **`org.gnome.glib.Glib`**

48

* **`org.gnome.glib.Handler`**

49

50

As with signal handlers, you have to be careful to get back from your callback

51

as soon as possible; you're blocking the main loop while that code is running.

52

53

Miscellaneous improvements

54

--------------------------

55

56

Other than this, we've accumulated a number of fixes and improvements over the

57

past months. Improvements to radio buttons, coverage of GtkSwitch, fixes to

58

Assistant, preliminary treatment of StyleContext, and improvements to

59

SourceView, FileChooser, and more. Compliments to Guillaume Mazoyer, Georgios

60

Migdos, and Alexander Boström for their contributions.

61

62

* **`org.gnome.gtk.Switch`**

63

* **`org.gnome.gtk.FileChooserButton`**

64

* **`org.gnome.gtk.ProgressBar`**

65

* **`org.gnome.gtk.Style`**

66

* **`org.gnome.gtk.StyleContext`**

67

* **`org.gnome.gtk.StyleProperty`**

68

* **`org.gnome.gtk.StyleRegion`**

69

* **`org.gnome.gtk.JunctionSides`**

70

* **`org.gnome.gtk.RegionFlags`**

71

72

java-gnome builds correctly when using Java 7. The minimum supported version

73

of the runtime is Java 6. This release depends on GTK 3.4.

74

75

AfC

76

77

78

79

java-gnome 4.1.1 (11 Jul 2011)

80

===============================

81

82

_To bump or not to bump; that is the question_

83

84

This is the first release in the 4.1 series. This introduces coverage of the

85

GNOME 3 series of libraries, notably GTK 3. There was a fairly significant API

86

change from GTK 2.x to 3.x, and we've done our best to accommodate it.

87

88

Drawing with Cairo, which you were already doing

89

------------------------------------------------

90

91

The biggest change has to do with drawing; if you have a custom widget (ie, a

92

DrawingArea) then you have to put your Cairo drawing code in a handler for the

93

[`Widget.Draw`][Widget.Draw] signal rather than what used to be

94

`Widget.ExposeEvent`. Since java-gnome has ever only exposed drawing via

95

Cairo, this change will be transparent to most developers using the library.

96

97

Other significant changes include colours: instead of the former `Color` class

98

there's now RGBA; you use this in calls in the `override...()` family instead

99

of `modify...()` family; for example see Widget's

100

[`overrideColor()`][Widget.overrideColor()].

101

102

* **`org.gnome.gdk.RGBA`**

103

* **`org.gnome.gtk.StateFlags`**

104

* **`org.gnome.gtk.Widget`**

105

* **`org.gnome.gtk.Widget.Draw`**

106

107

Orientation is allowed now

108

--------------------------

109

110

Widgets that had abstract base classes and then concrete horizontal and

111

vertical subclasses can now all be instantiated directly with an Orientable

112

parameter. The most notable example is Box's [`<init>()`][Box.<init>()] (the

113

idea is to replace [VBox][] and [HBox][], which upstream is going to do away

114

with). Others are [Paned][], various `Range` subclasses such as

115

[Scrollbar][]. [Separator][], [Toolbar][], and [ProgressBar][] now implement

116

Orientable as well.

117

118

* **`org.gnome.gtk.Scrollbar`**

119

* **`org.gnome.gtk.Toolbar`**

120

* **`org.gnome.gtk.Box`**

121

* **`org.gnome.gtk.Paned`**

122

* **`org.gnome.gtk.ProgressBar`**

123

* **`org.gnome.gtk.Separator`**

124

* **`org.gnome.gtk.Toolbar`**

125

126

There's actually a new layout Container, however. Replacing Box and Table

127

is [Grid][]. Grid is optimized for GTK's new height-for-width geometry

128

management and should be used in preference to other Containers.

129

130

* **`org.gnome.gtk.Grid`**

131

132

The [ComboBox][] API was rearranged somewhat. The text-only type is now

133

[ComboBoxText][]; the former ComboBoxEntry is gone and replaced by a ComboBox

134

property. This is somewhat counter-intuitive since the behaviour of the Widget

135

is so dramatically different when in this mode (ie, it looks like a

136

ComboBoxEntry; funny, that).

137

138

* **`org.gnome.gtk.ComboBox`**

139

* **`org.gnome.gtk.ComboBoxText`**

140

141

Other improvements

142

------------------

143

144

It's been some months since our last release, and although most of the work

145

has focused on refactoring to present GTK 3, there have been numerous other

146

improvements. Cairo in particular has seen some refinement in the area of

147

Pattern and [Filter][] handling thanks to Will Temperley, and coverage of

148

additional [TextView][] and [TextTag][] properties, notably relating to

149

paragraph spacing and padding.

150

151

* **`org.freedesktop.cairo.Filter`**

152

* **`org.freedesktop.cairo.Pattern`**

153

* **`org.gnome.gtk.TextTag`**

154

* **`org.gnome.gtk.TextView`**

155

156

Thanks to Kenneth Prugh, Serkan Kaba, and Guillaume Mazoyer for their help

157

porting java-gnome to GNOME 3.

158

159

AfC

160

161

[HBox]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/HBox.html>

162

[VBox]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/VBox.html>

163

[Paned]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Paned.html>

164

[Separator]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Separator.html>

165

[Scrollbar]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Scrollbar.html>

166

[ProgressBar]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/ProgressBar.html>

167

[ToolBar]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/ToolBar.html>

168

[Box.<init>()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Box.html#Box(org.gnome.gtk.Orientation,%20int)>

169

[Grid]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Grid.html>

170

[ComboBox]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/ComboBox.html>

171

[ComboBoxText]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/ComboBoxText.html>

172

[Widget.Draw]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Widget.Draw.html>

173

[Widget.overrideColor()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Widget.html#overrideColor(org.gnome.gtk.StateFlags,%20org.gnome.gdk.RGBA)>

174

[TextTag]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/TextTag.html>

175

[Filter]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/cairo/Filter.html>

176

177

178

179

java-gnome 4.0.20 (11 Jul 2011)

180

===============================

181

182

This will be the last release in the 4.0 series. It is meant only as an aide

183

to porting over the API bump between 4.0 and 4.1; if your code builds against

184

4.0.20 without reference to any deprecated classes or methods then you can be

185

fairly certain it will build against 4.1.1; if we've missed something please

186

let us know.

187

188

* <strike>**`org.gnome.gdk.Color`**</strike>

189

* <strike>**`org.gnome.gdk.Colormap`**</strike>

190

* <strike>**`org.gnome.gdk.EventExpose`**</strike>

191

* <strike>**`org.gnome.gdk.Drawable`**</strike>

192

* <strike>**`org.gnome.gdk.Pixmap`**</strike>

193

* <strike>**`org.gnome.gdk.Bitmap`**</strike>

194

* <strike>**`org.gnome.gdk.Region`**</strike>

195

* <strike>**`org.gnome.gtk.Widget.ExposeEvent`**</strike>

196

* <strike>**`org.gnome.gtk.StateType`**</strike>

197

* <strike>**`org.gnome.gtk.Ruler`**</strike>

198

* <strike>**`org.gnome.gtk.Object`**</strike>

199

* <strike>**`org.gnome.gtk.Item`**</strike>

200

* <strike>**`org.gnome.gtk.ComboBoxEntry`**</strike>

201

* <strike>**`org.gnome.gtk.TextComboBox`**</strike>

202

* <strike>**`org.gnome.gtk.TextComboBoxEntry`**</strike>

203

* <strike>**`org.gnome.glade.Glade`**</strike>

204

* <strike>**`org.gnome.glade.XML`**</strike>

205

206

AfC

207

208

Website update

209

==============

210

211

We've reorganized the java-gnome website. API Documentation is now found at

212

[`doc/api/4.1/`](/doc/api/4.1/overview-summary.html). This prepares us for the

213

upcoming API bump.

214

215

AfC

216

217

218

219

java-gnome 4.0.19 (14 Feb 2011)

220

===============================

221

222

_What do you mean that's not the font I asked for?_

223

224

This release includes some minor feature enhancements.

225

226

Preliminary coverage of Pango's Font object. Font is Pango's abstraction

227

describing a typeface, and is what is actually loaded. We've exposed the

228

methods that allow you to find out what was _actually_ loaded for a given

229

FontDescription request. You do this with Context's

230

[`loadFont()`][Context.loadFont()] and then Font's

231

[`describe()`][Font.describe()]. Thanks to Behdad Esfahbod for explaining how

232

all this works.

233

234

* **`org.gnome.pango.Font`**

235

* **`org.gnome.pango.Context`**

236

237

Exposed a few utility functions, including one to find out if your program is

238

running in a terminal or from the Desktop directly.

239

240

* **`org.freedesktop.bindings.Environment`**

241

242

GTK improvements

243

----------------

244

245

Further improved some corner cases involved in using Actions, and now you can

246

make them with named Icons.

247

248

* **`org.gnome.gtk.Action`**

249

* **`org.gnome.gtk.ToolItem`**

250

251

There are some odd corner cases, especially with TextView, where idle handlers

252

need to run before you have the calculations you need ready to query. One

253

workaround appears to be letting the main loop cycle, so we've exposed

254

[`Gtk.mainIterationDo()`][Gtk.mainIterationDo()] and the `Gtk.eventsPending()`

255

which wraps it.

256

257

* **`org.gnome.gtk.Gtk`**

258

259

Build improvements

260

------------------

261

262

Building java-gnome on Mandriva now works! Thanks to Liam Quin for helping QA

263

the top level `configure` script.

264

265

AfC

266

267

[Gtk.mainIterationDo()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Gtk.html#mainIterationDo(boolean)>

268

[Context.loadFont()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/pango/Context.html#loadFont(org.gnome.pango.FontDescription)>

269

[Font.describe()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/pango/Font.html#describe()>

270

271

272

273

java-gnome 4.0.18 (23 Dec 2010)

274

===============================

275

276

_My compressed original is better than your uncompressed copy_

277

278

This is a bug fix release. A serious crasher was occurring when you requested

279

a the underlying [org.gnome.gdk] Window backing a Widget, as is often

280

necessary before popping up context menus. Thanks to Kenneth Prugh and

281

Guillaume Mazoyer for their help in duplicating and isolating the problem.

282

283

Better image rendering

284

----------------------

285

286

While we're at it, we've merged work in progress offering coverage of the

287

librsvg Scalable Vector Graphics loader. This allows you to draw an SVG image

288

as a vector graphic to Cairo (which itself works in vector form, of course),

289

and is a substantial improvement over just loading the `.svg` with gdk-pixbuf

290

(which rasterizes the graphic to a bitmap first, of course). Load the image

291

with [Handle][], then draw it with Context's

292

[`showHandle()`][Context.showHandle()].

293

294

* **`org.freedesktop.cairo.Context`**

295

* **`org.gnome.rsvg.Handle`**

296

* **`org.gnome.rsvg.DimensionData`**

297

* `org.gnome.rsvg.Plumbing`

298

* `org.gnome.rsvg.RsvgDimensionDataOverride`

299

* `org.gnome.rsvg.ValidateVectorIllustrations`

300

* `cairo.ExampleDrawingPenguins`

301

302

We've also added coverage of Cairo Surface's new

303

[`setMimeType()`][Surface.setMimeType()], which allows you to embed the the

304

original [ie JPEG, or to a lesser extent PNG] image in PDF output rather than

305

just the decoded, rasterized, and very huge bitmap image that Cairo uses on

306

screen and would otherwise have used in PDF and SVG output. So 100 kB JPEGs

307

stay JPEGs instead of turning into 12 MB bitmaps. Yeay.

308

309

* **`org.freedesktop.cairo.Surface`**

310

* **`org.freedesktop.cairo.RecordingSurface`**

311

* **`org.freedesktop.cairo.MimeType`**

312

* `org.freedesktop.cairo.CairoSurfaceOverride`

313

* `org.freedesktop.cairo.ValidateCairoInternals`

314

315

java-gnome now depends on Cairo 1.10 and librsvg 2.32.

316

317

AfC

318

319

[Handle]: http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/rsvg/Handle.html

320

[Context.showHandle()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/cairo/Context.html#showHandle(org.gnome.rsvg.Handle)>

321

[Surface.setMimeType()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/cairo/Surface.html#setMimeData(org.freedesktop.cairo.MimeType,%20byte[])>

322

323

324

325

java-gnome 4.0.17 (18 Nov 2010)

326

===============================

327

328

_All dictionaries are equal. But some dictionaries are more equal than

329

others._

330

331

After some 6 months of development, this release includes substantial

332

improvements across the library. Thanks to Guillaume Mazoyer, Michael

333

Culbertson, Douglas Goulart, Vreixo Formoso, Mauro Galli, Thijs Leibbrand, and

334

Andrew Cowie for their contributions to the library, and also to Yaakov

335

Selkowitz, and Alexander Boström for their updates to the build system.

336

337

Enchant Dictionaries

338

--------------------

339

340

Improve the utility of the Enchant library by exposing functionality to test

341

wither a dictionary [exists][Enchant.existsDictionary()] for a given "language

342

tag", and to [list][Enchant.listDictionaries()] all available dictionaries.

343

Add speciality functions to the Internationalization class facilitating the

344

translation of [language][Internationalization.translateLangageName()] and

345

[country][Internationalization.translateCountryName()] names so you can

346

present the list of available languages properly translated in the user's

347

language.

348

349

* **`org.freedesktop.enchant.Enchant`**

350

* **`org.freedesktop.bindings.Internationalization`**

351

* `org.freedesktop.enchant.EnchantBrokerOverride`

352

* `org.freedesktop.enchant.ValidateEnchantInternals`

353

* `org.freedesktop.bindings.ValidateInternationalization`

354

355

GTK improvements

356

----------------

357

358

Introduce Icon as a strongly typed class to wrap "named icons" available in an

359

icon theme, complementing the previous coverage of "stock icons" provided by

360

the Stock class. Add methods to DataColumn, TreeModel, Image, and Entry making

361

these available.

362

363

* **`org.freedesktop.icons.Icon`**

364

* `org.freedesktop.icons.Helper`

365

* **`org.freedesktop.icons.ActionIcon`**

366

* **`org.freedesktop.icons.ApplicationIcon`**

367

* **`org.freedesktop.icons.CategoryIcon`**

368

* **`org.freedesktop.icons.DeviceIcon`**

369

* **`org.freedesktop.icons.EmblemIcon`**

370

* **`org.freedesktop.icons.FaceIcon`**

371

* **`org.freedesktop.icons.MimeIcon`**

372

* **`org.freedesktop.icons.PlaceIcon`**

373

* **`org.freedesktop.icons.StateIcon`**

374

* **`org.gnome.gtk.DataColumnIcon`**

375

* **`org.gnome.gtk.TreeModel`**

376

* **`org.gnome.gtk.Image`**

377

* **`org.gnome.gtk.Entry`**

378

* `org.freedesktop.icons.ValidateIconItems`

379

380

Also in TreeView land, Vreixo Foromso contributed a change to make

381

DataColumnReference generic, noting that this was his "one great irritation"

382

with java-gnome. Itch scratched, apparently. `:)`

383

384

* **`org.gnome.gtk.TreeModel`**

385

* **`org.gnome.gtk.DataColumnReference`**

386

* `org.gnome.gtk.ValidateTreeModel`

387

388

A fair bit of work went into polishing coverage in various classes. We now

389

have coverage for Adjustment's various properties (necessary if you want to

390

drive a scroll bar around yourself without using one built into a

391

ScrolledWindow).

392

393

* **`org.gnome.gtk.Adjustment`**

394

* **`org.gnome.gtk.HScrollbar`**

395

* **`org.gnome.gtk.VScrollbar`**

396

* `org.gnome.gtk.ValidateAssistant`

397

* `org.gnome.gtk.ValidateProperties`

398

* `org.gnome.gtk.ValidateSignalEmission`

399

400

We've also introduced a new signal in the [Assistant][]. You can now define

401

the behaviour of an Assistant using the `ForwardPage` signal with the

402

`setForwardPageCallback()` method. It can help you to skip pages when you need

403

to. When going back, the Assistant will also skip the previously skipped page.

404

405

* **`org.gnome.gtk.Assistant`**

406

* `org.gnome.gtk.GtkAssistantOverride`

407

* `org.gnome.gtk.ValidateAssistant`

408

409

java-gnome now supports GTK+ 2.20 and introduces the new [Spinner][] widget

410

that can be used to display an unknown progress.

411

412

* **`org.gnome.gtk.Spinner`**

413

* **`org.gnome.gtk.CellRendererSpinner`**

414

415

Added coverage for another utility function, this time the one that

416

[escapes][Glib.markupEscapeText()] text in strings so that it can be safely

417

included when Pango markup is being used.

418

419

* **`org.gnome.glib.Glib`**

420

421

If you need to ensure whatever has been copied to the clipboard is available

422

after your application terminates, you can call Clipboard's `store()`.

423

424

* **`org.gnome.gtk.Clipboard`**

425

426

Thread safety

427

-------------

428

429

Fixed a fairly serious bug in the interaction between the memory management

430

code and the thread safety mechanism. Amazing we got away with this one so

431

long, really. Thanks to Vreixo Formoso for helping with analysis of the crash

432

dumps, confirming the diagnosis, and double checking the proposed solution.

433

The problem only showed up if you were making extensive use of something like

434

TextViews which (internal to GTK) did its drawing in a background idle

435

handler.

436

437

* `org.gnome.glib.GObject`

438

439

Also fixed a crasher that turned up if your cursor theme didn't have a certain

440

named cursor. `ENOTGNOME`, but anyway.

441

442

* **`org.gnome.gdk.Cursor`**

443

444

More drawing

445

------------

446

447

The Cairo graphics library continues to be a joy to use and we continue to

448

make minor improvements to our coverage as people use it more. In particular,

449

based on help from Benjamin Otte and others we've refined the way you create a

450

[Context][] in a `Widget.ExposeEvent`, improving efficiency and taking

451

advantage of some of the underlying support functions more effectively.

452

453

* **`org.freedesktop.cairo.Extend`**

454

* **`org.freedesktop.cairo.FillRule`**

455

* **`org.freedesktop.cairo.HintStyle`**

456

* **`org.freedesktop.cairo.Context`**

457

* **`org.freedesktop.cairo.FontOptions`**

458

* **`org.freedesktop.cairo.Pattern`**

459

* **`org.gnome.gdk.Color`**

460

* **`org.gnome.pango.Layout`**

461

* **`org.gnome.pango.Underline`**

462

* `org.freedesktop.cairo.GdkCairoSupport`

463

* `org.freedesktop.cairo.ValidateCairoContext`

464

465

Looking ahead

466

-------------

467

468

With GTK 3.0 coming closer to reality, we're keeping close track of the

469

activity there. GTK 3.0 is a pretty vast API and ABI break from 2.x with some

470

fairly major changes to the way Widget sizing works, along with an overhaul of

471

the drawing system. We'll be updating java-gnome to meet these changes in the

472

months to come.

473

474

AfC, GM

475

476

[Enchant.existsDictionary()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/enchant/Enchant.html#existsDictionary(java.lang.String)>

477

[Enchant.listDictionaries()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/enchant/Enchant.html#listDictionaries()>

478

[Internationalization.translateLangageName()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/bindings/Internationalization.html#translateLanguageName(java.lang.String)>

479

[Internationalization.translateCountryName()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/bindings/Internationalization.html#translateCountryName(java.lang.String)>

480

[Assistant]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Assistant.html>

481

[Spinner]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/gtk/Spinner.html>

482

[Glib.markupEscapeText()]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/gnome/glib/Glib.html#markupEscapeText(java.lang.String)>

483

[Context]: <http://java-gnome.sourceforge.net/doc/api/4.1/org/freedesktop/cairo/Context.html#Context(org.gnome.gdk.EventExpose)>

484

485

486

487

488

java-gnome 4.0.16 (17 Jun 2010)

489

===============================

490

491

_Accelerating is good for you_

492

493

Accelerators

494

------------

495

496

java-gnome now has full support for accelerators, the key bindings (such as

497

**`Ctrl+Q`** for "quit") typically used to activate MenuItems and Actions. The

498

heart of the API is in the [AcceleratorGroup][] class, although you actually

499

use it care of MenuItem's `setAccelerator()` and Action's `setAccelerator()`.

500

Huge thanks are due to Thijs Leibbrand for having navigating the almost

501

incomprehensible native API and figured out how we could best add coverage for

502

Java programs.

503

504

* **`org.gnome.gtk.AcceleratorGroup`**

505

* **`org.gnome.gtk.Menu`**

506

* **`org.gnome.gtk.MenuItem`**

507

* **`org.gnome.gtk.ImageMenuItem`**

508

* **`org.gnome.gtk.Window`**

509

* **`org.gnome.gtk.Action`**

510

* `menu.ExampleSimpleMenu`

511

512

Cairo Operations

513

----------------

514

515

Though we've had support for Cairo's various "operators" (different modes for

516

combining what's being drawn with what's already on the surface) for some

517

time, we didn't really know what we were doing. Thanks to the careful work of

518

Kenneth Prugh, we've now got full coverage in the [Operator][] class along

519

with a magnificent series of illustrations. These are the same pictures as are

520

in the underlying Cairo documentation, but like our screenshots, ours are

521

generated automatically by java-gnome programs whenever you build the

522

documentation.

523

524

* **`org.freedesktop.cairo.Operator`**

525

* `Harness`

526

* `org.freedesktop.cairo.IllustrationOperatorOver`

527

* `org.freedesktop.cairo.IllustrationOperatorDestOver`

528

* `org.freedesktop.cairo.IllustrationOperatorSaturate`

529

* `org.freedesktop.cairo.IllustrationOperatorDestIn`

530

* `org.freedesktop.cairo.IllustrationOperatorDestAtop`

531

* `org.freedesktop.cairo.Illustration`

532

* `org.freedesktop.cairo.IllustrationOperatorAdd`

533

* `org.freedesktop.cairo.IllustrationOperatorDest`

534

* `org.freedesktop.cairo.IllustrationOperatorAtop`

535

* `org.freedesktop.cairo.IllustrationOperatorSource`

536

* `org.freedesktop.cairo.IllustrationOperatorClear`

537

* `org.freedesktop.cairo.IllustrationOperatorDestOut`

538

* `org.freedesktop.cairo.IllustrationOperatorOut`

539

* `org.freedesktop.cairo.IllustrationOperator`

540

* `org.freedesktop.cairo.IllustrationOperatorXOR`

541

* `org.freedesktop.cairo.IllustrationOperatorIn`

542

543

Miscellaneous improvements

544

--------------------------

545

546

The style `CENTER` has been added in ButtonBoxStyle.

547

548

* **`org.gnome.gtk.ButtonBoxStyle`**

549

550

Coverage of GTK's new [InfoBar][] Widget was added by Guillaume Mazoyer, who

551

also made numerous touch ups to various core classes. The Activatable and

552

Editable interfaces got some love. And methods to get "human readable" byte

553

sizes have been added to the [Glib][] utility class.

554

555

* **`org.gnome.gtk.Activatable`**

556

* **`org.gnome.gtk.Editable`**

557

* **`org.gnome.gtk.Entry`**

558

* **`org.gnome.gtk.EntryBuffer`**

559

* **`org.gnome.gtk.InfoBar`**

560

* **`org.gnome.glib.Glib`**

561

* **`org.gnome.gtk.Widget`**

562

* **`org.gnome.gtk.StatusIcon`**

563

* `org.gnome.glib.ValidateUtilityFunctions`

564

* `org.gnome.gtk.ValidateEntry`

565

566

Finally, we exposed the code needed to force GDK to revert to the pre GTK 2.18

567

behaviour of using native X Windows for every Widget. This shouldn't be

568

necessary -- the whole point of major changes like the "client-side windows"

569

branch are is that they are supposed to Just Work (and more to the point Just

570

Work better, over time) -- but it does give a workaround for unusual corner

571

cases where either GTK, java-gnome, or the developer is constrained and needs

572

some help.

573

574

* **`org.gnome.gdk.Window`**

575

576

AfC

577

578

[InfoBar]: doc/api/4.1/org/gnome/gtk/InfoBar.html

579

[AcceleratorGroup]: doc/api/4.1/org/gnome/gtk/AcceleratorGroup.html

580

[Operator]: doc/api/4.1/org/freedesktop/cairo/Operator.html

581

[Glib]: doc/api/4.1/org/gnome/glib/Glib.html

582

583

584

585

java-gnome 4.0.15 (16 Mar 2010)

586

===============================

587

588

_Radio things_

589

590

This has mostly been a bug fix cycle with numerous internal quality

591

improvements being made. A few developer visible API additions have been made,

592

summarized below.

593

594

Unified radio handling

595

----------------------

596

597

There are a number of controls in GTK that exhibit the "radio" behaviour of

598

being in a group of which only one can be selected: RadioButton,

599

RadioMenuItem, RadioToolButton and RadioAction. We originally had a class

600

called RadioButtonGroup which was used when constructing RadioButtons to

601

indicate which group they were a member of. In introducing overage of the

602

other radio types, Guillaume Mazoyer implemented a generic grouping class

603

called RadioGroup which is now used for all the radio types.

604

605

* **`org.gnome.gtk.RadioGroup`**

606

* **`org.gnome.gtk.RadioButton`**

607

* **`org.gnome.gtk.RadioMenuItem`**

608

* **`org.gnome.gtk.RadioToolButton`**

609

* **`org.gnome.gtk.RadioAction`**

610

611

XDG utility functions

612

---------------------

613

614

A number of utility functions (aka static methods) were added to Glib allowing

615

you to access the various user and systems directories as specified by the XDG

616

specification. These are `Glib.getUserConfigDir()`, `Glib.getUserDataDir()`

617

and friends.

618

619

* **`org.gnome.glib.UserDirectory`**

620

* **`org.gnome.glib.Glib`**

621

622

Miscellaneous improvements

623

--------------------------

624

625

Better control of positioning when popping up context menus; you can specify

626

co-ordinates when calling Menu's `popup()`.

627

628

* **`org.gnome.gtk.Menu`**

629

* `org.gnome.gtk.GtkMenuOverride`

630

631

The no-arg "convenience" packing methods we invented for HBox and VBox were

632

causing more trouble than they were worth because people we not understanding

633

the implications of the "default" packing values. So these are deprecated; the

634

full four-argument `packStart()` and `packEnd()` have been present for a long

635

time and are to be used in preference.

636

637

* **`org.gnome.gtk.Box`**

638

639

Serkan Kaba spent a bit of time working with the text version of the ComboBox

640

API. Apparently no one had needed `removeText()` so he added that.

641

642

* **`org.gnome.gtk.TextComboBox`**

643

644

A number of improvements to the coverage of GDK's event masks were merged.

645

This is work originally by Vreixo Formoso necessary to support the

646

`Widget.MotionNotifyEvent` signal, though it has use in other applications.

647

Widget now has `addEvents()` and `setEvents()` to this end.

648

649

* **`org.gnome.gtk.Widget`**

650

* `org.gnome.gtk.GtkWidgetOverride`

651

* **`org.gnome.gdk.EventMotion`**

652

* **`org.gnome.gdk.EventMask`**

653

654

Finally, Guillaume needed to handle selections in IconViews. The API is

655

similiar to that in TreeView, but doesn't use the same TreeSelection helper

656

class; the methods are directly on IconView. Boo for asymmetry. Anyway, we've

657

exposed isSelected() on both TreeSelection and IconView so you can find out if

658

a given TreePath is currently selected.

659

660

* **`org.gnome.gtk.IconView`**

661

* **`org.gnome.gtk.TreeSelection`**

662

* `org.gnome.gtk.ValidateIconView`

663

664

Better initialization checking

665

------------------------------

666

667

Logic checking that the library has been properly initialized has been

668

refactored, making it harder to accidentally misuse java-gnome when getting

669

started \[or when starting a new program after you've been using the library

670

for years and forgotten the basics `:)`\].

671

672

Last but not least, a number of bug fixes; one was developer-visible;

673

`Enchant.requestDictionary()` now returns `null` like it claimed to if you

674

request an unknown dictionary. Nice catch, Serkan.

675

676

* **`org.freedesktop.enchant.Enchant`**

677

* `org.freedesktop.enchant.Plumbing`

678

* `org.freedesktop.enchant.ValidateEnchantInternals`

679

680

All the source files have the full (ie traditional) GPL v2 header text now;

681

the files comprising the library as used at run-time have GPL headers text +

682

the Classpath Exception text. Needed to be done. Makes for a large diff this

683

release, but makes the

684

[Ohloh](http://www.ohloh.net/p/java-gnome/analyses/latest)'s page for

685

java-gnome happy too `:)`.

686

687

AfC

688

689

690

691

java-gnome 4.0.14 (16 Dec 2009)

692

===============================

693

694

_You have to compose in order to enchant_

695

696

Access to Enchant spell checking API

697

------------------------------------

698

699

Coverage of the Enchant spell checking facade (which was already an implicit

700

dependency arising from our GtkSpell coverage) is now included in java-gnome.

701

It's a lovely library with a simple to use API which in turn fronts for

702

various back end spelling providers.

703

704

* **`org.freedesktop.enchant.Enchant`**

705

* **`org.freedesktop.enchant.Dictionary`**

706

* `org.freedesktop.enchant.Broker`

707

* `org.freedesktop.enchant.ValidateEnchantInternals`

708

709

More detailed input handling

710

----------------------------

711

712

GTK's handling of complex input methods is extraordinarily powerful, and of

713

course present by default in the Entry and TextView text entry Widgets. If

714

you're doing your own text based work, however, you might need to capture the

715

results of an input method being used to compose characters or words.

716

`InputMethod.Commit` is where the result of a compose sequence is captured and

717

delivered to the application.

718

719

* **`org.gnome.gtk.InputMethod`**

720

* **`org.gnome.gtk.SimpleInputMethod`**

721

* **`org.gnome.gtk.MulticontextInputMethod`**

722

* `org.gnome.gtk.ValidateInputMethods`

723

724

We've also made numerous improvements down in GDK where events are processed;

725

as a Java library we represent many naked low-level native entities with

726

strongly-typed classes, and have improved our coverage here, notably with new

727

Cursor constants representing the common use cases of changing the pointer.

728

729

* **`org.gnome.gdk.Keyval`**

730

* **`org.gnome.gdk.ModifierType`**

731

* **`org.gnome.gdk.Cursor`**

732

* **`org.gnome.gdk.CursorType`**

733

734

Improved text rendering

735

-----------------------

736

737

Other minor improvements are present across the text rendering stack, notably

738

with the ability to introspect where a Pango Layout has made its line breaks

739

when wrapping via LayoutLine's `getStartIndex()` and `getLength()` methods.

740

741

* **`org.gnome.gtk.TextIter`**

742

* **`org.gnome.gtk.TextTag`**

743

* `org.gnome.pango.ValidateTextBuffer`

744

* **`org.gnome.pango.LayoutLine`**

745

* `org.gnome.pango.ValidatePangoWrapBehaviour`

746

747

Guillaume Mazoyer finished up a work by Serkan Kaba resulting in us having

748

coverage of the special LinkButton subclass of Button which can be used to

749

present clickable URLs.

750

751

* **`org.gnome.gtk.LinkButton`**

752

* `org.gnome.gtk.ValidateLinkBehaviour`

753

* `button.ExampleDocumentationLink`

754

755

You can now create custom PaperSize objects, which is handy if you need to use

756

Cairo to output PDF documents with a non-standard paper format.

757

758

* **`org.gnome.gtk.CustomPaperSize`**

759

* `org.gnome.gtk.ValidatePrinting`

760

761

Other changes

762

-------------

763

764

You can now use gdk-pixbuf to query an image on disk for its dimensions via

765

Pixbuf `getFileInfo()` function calls.

766

767

* **`org.gnome.gdk.Pixbuf`**

768

* `org.gnome.gdk.ValidateImageHandling`

769

770

There were of course miscellaneous improvements to various long established

771

core classes, mostly fixing typos.

772

773

* **`org.gnome.gtk.Dialog`**

774

* **`org.gnome.gtk.AboutDialog`**

775

* **`org.gnome.gtk.TreeIter`**

776

* **`org.gnome.gtk.TreeModelFilter`**

777

* `org.gnome.gtk.ValidateTreeStore`

778

* **`org.gnome.gtk.Window`**

779

* **`org.gnome.pango.Attribute`**

780

781

We now have the methods necessary to have ImageMenuItems actually show images

782

(there's a GNOME bug whereby suddenly icons are not showing in menus. So you

783

need to either explicitly tell an ImageMenuItem that it should always show its

784

image, or use the global Settings to say that Menus and Buttons should always

785

have their icons showing).

786

787

* **`org.gnome.gtk.ImageMenuItem`**

788

* **`org.gnome.gtk.Settings`**

789

* `org.gnome.gtk.ValidateGlobalSettings`

790

791

The internal initialization sequence has been tweaked to ensure that GLib's

792

threads are initialized before anything else. This means java-gnome apps will

793

work if `glib 2.22.3` is installed; this is a workaround for bug

794

[603774](https://bugzilla.gnome.org/show_bug.cgi?id=603774).

795

796

Headless testing

797

----------------

798

799

For a long time we've had to be careful in our test suite not to do anything

800

that would cause a Window to appear or otherwise popup while the tests were

801

running. But some for some test cases this is unavoidable, especially if the

802

main loop needs to cycle. We now run the java-gnome test suite within a

803

virtual X server (ie `Xvfb`), and as a result distros packaging the library

804

can run the test suite on their headless build servers if they wish.

805

806

There's a new base class for java-gnome TestCases needing to run in this

807

environment.

808

809

* `org.gnome.gtk.GraphicalTestCase`

810

811

Looking ahead

812

-------------

813

814

What's ahead for java-gnome? That's always a good question. At this point

815

java-gnome provides a comprehensive API for development of user interfaces

816

suitable for the GNOME desktop, and it's incredibly rewarding to see people

817

using the library for their own programs.

818

819

Development of java-gnome has continued pretty steadily, driven by people

820

finding they need additional features from some of the underlying GNOME and

821

FreeDesktop libraries we already expose. As a community we also work to

822

fine-tune the performance and quality of the library through continuous

823

improvement of the code base and its algorithms.

824

825

There are also people quietly working on experimental coverage of more unusual

826

libraries such as GStreamer and Clutter which is pretty exciting to see.

827

828

People using java-gnome are always welcome to join us in `#java-gnome` to ask

829

questions or just hang out! So happy hacking, and see you soon.

830

831

AfC

832

833

834

835

java-gnome 4.0.13 (27 Aug 2009)

836

===============================

837

838

_Unicode. It's bigger than you think._

839

840

This is a bug fix release to address a serious weakness in Java's handling of

841

Unicode characters.

842

843

Unicode handling

844

----------------

845

846

It turns out that Java's chars are **not** pure Unicode codepoints. Most

847

people know that Java String objects are arrays of Java chars, but in

848

aggregate they are encoded in UTF-16 in order to deal with the fact that there

849

are Unicode characters whose index is higher than `0xFFFF` and which need more

850

than two bytes to identify them. It's a problem that an application developer

851

has to deal with if they're using high-range "supplementary" Unicode

852

characters, but wasn't something that would break java-gnome...

853

854

Except it turns out that the Java VM does not do UTF-8 translation properly.

855

It has a hard wired limitation preventing it from writing out UTF-8 sequences

856

longer than 3 bytes. Who knows what crack they were smoking when they decided

857

that one. But things like TextView / TextBuffer work in characters, so we need

858

characters. (actually, they work in UTF-8 bytes, but the offsets in our public

859

API are the characters variants).

860

861

Luckily, we can get at the raw UTF-16 arrays backing Strings, and so in

862

combination with GLib's character set conversion functions, we've been able to

863

redo our string handling internally so as to have correct treatment of Unicode

864

codepoints. Lots of testing.

865

866

* `org.gnome.gtk.ValidateUnicode`

867

* `org.gnome.gtk.ValidateTextBuffer`

868

* **`org.gnome.gtk.TextIter`**

869

870

This surgery was almost entirely internal; Strings returned by java-gnome

871

methods are of course still Java String objects. There was only one signature

872

change in the public API: TextIter's `getChar()` now returns Java int, not

873

Java char.

874

875

New coverage

876

------------

877

878

<img src="doc/api/4.1/org/gnome/gtk/Entry.png" alt="" style="float: right;

879

text-align: right; padding-left: 15px;" /> This release also features the work

880

of Guillaume Mazoyer exposing some of the new features available in Entry

881

Widgets, including displaying icons and showing progress bars in the

882

background.

883

884

* **`org.gnome.gtk.Entry`**

885

* **`org.gnome.gtk.EntryIconPosition`**

886

* `org.gnome.gtk.ValidateEntry`

887

* `org.gnome.gtk.SnapshotEntryIcon`

888

* `entry.ExampleSearchSomeone`

889

890

Along with minor enhancements to various miscellaneous classes.

891

892

* **`org.gnome.gdk.ModifierType`**

893

* **`org.gnome.gtk.Label`**

894

* **`org.gnome.pango.EllipsizeMode`**

895

* **`org.gnome.pango.RiseAttribute`**

896

897

With this release, java-gnome now requires GTK `2.16` or newer.

898

899

AfC

900

901

902

903

java-gnome 4.0.12 (24 Jul 2009)

904

===============================

905

906

_Being Uniquely Notified while Spelling the Sources you are Viewing is good

907

for the soul._

908

909

In addition to ongoing improvement in our coverage of the GTK widget toolkit,

910

the next release of java-gnome begins to realize our vision to offer

911

coverage of the broad suite of libraries making up the GNOME desktop.

912

913

New Coverage

914

------------

915

916

The TextView text editing Widget has received two significant capability

917

boosts. With the work of Stefan Schweizer, we now have coverage of the

918

powerful GtkSourceView library with its impressive built-in multi

919

\[programming\] language source highlighting features.

920

921

* **`org.gnome.sourceview.Language`**

922

* **`org.gnome.sourceview.LanguageManager`**

923

* `org.gnome.sourceview.Plumbing`

924

* **`org.gnome.sourceview.SourceBuffer`**

925

* **`org.gnome.sourceview.SourceView`**

926

* `org.gnome.sourceview.ValidateSourceView`

927

* `sourceview.ExampleEditor`

928

929

And with the contribution of GtkSpell coverage by Serkan Kaba, we can now

930

offer spell checking in TextViews as well.

931

932

* **`org.gnome.gtk.Spell`**

933

* **`org.gnome.gtk.TextView`**

934

* `org.gnome.gtk.ValidateTextViewSpelling`

935

* `org.gnome.gtk.SnapshotTextViewSpelling`

936

* `textview.ExampleInstantMessenger`

937

938

Two other GNOME libraries feature in this release. Serkan also contributed

939

excellent coverage of LibNotify, enabling an application to create and send

940

popups to be displayed by the desktop notification mechanism.

941

942

* **`org.gnome.notify.Notification`**

943

* **`org.gnome.notify.Notify`**

944

* **`org.gnome.notify.Urgency`**

945

* `org.gnome.notify.Plumbing`

946

* `notify.ExampleLowBattery`

947

948

And, we expose LibUnique, which offers DBus-powered machinery enabling a

949

developer to ensure only one instance of their application is running.

950

951

* **`org.gnome.unique.Application`**

952

* **`org.gnome.unique.Command`**

953

* **`org.gnome.unique.MessageData`**

954

* `org.gnome.unique.Plumbing`

955

* **`org.gnome.unique.Response`**

956

* `org.gnome.unique.ValidateUniqueApplications`

957

* `unique.ExampleThereCanBeOnlyOne`

958

959

Continuing improvement

960

----------------------

961

962

Lots of minor changes and enhancements throughout the core GTK libraries.

963

Highlights include improved mouse button handling, filtering when choosing

964

files, and further refinement to Pixbuf. Thanks to Peter Mossveld, Kenneth

965

Prugh, Vreixo Formoso, Serkan Kaba.

966

967

* **`org.freedesktop.cairo.Context`**

968

* `org.freedesktop.cairo.Status`

969

* `org.freedesktop.cairo.ValidateCairoContext`

970

* **`org.gnome.gdk.CursorType`**

971

* **`org.gnome.gdk.EventScroll`**

972

* **`org.gnome.gdk.MouseButton`**

973

* **`org.gnome.gdk.Pixbuf`**

974

* **`org.gnome.gdk.ScrollDirection`**

975

* **`org.gnome.gtk.AboutDialog`**

976

* **`org.gnome.gtk.CellRendererProgress`**

977

* **`org.gnome.gtk.ColorButton`**

978

* **`org.gnome.gtk.Entry`**

979

* **`org.gnome.gtk.FileChooser`**

980

* **`org.gnome.gtk.FileChooserButton`**

981

* **`org.gnome.gtk.FileChooserDialog`**

982

* **`org.gnome.gtk.FileChooserWidget`**

983

* **`org.gnome.gtk.FileFilter`**

984

* **`org.gnome.gtk.Notebook`**

985

* **`org.gnome.gtk.Range`**

986

* **`org.gnome.gtk.Toolbar`**

987

* **`org.gnome.gtk.ToolbarStyle`**

988

* **`org.gnome.gtk.Widget`**

989

* `org.freedesktop.bindings.ValidateInternationalization`

990

* `org.gnome.gtk.ValidateProperties`

991

* `org.gnome.gtk.ValidateTextBuffer`

992

993

Finally, thanks to Guillaume Mazoyer we now have coverage of EntryCompletion,

994

the feature of Entry Widgets whereby available possible completions are

995

offered to the based on characters the user has typed so far.

996

997

* **`org.gnome.gtk.EntryCompletion`**

998

* `org.gnome.gtk.ValidateEntryCompletion`

999

* `org.gnome.gtk.SnapshotEntryCompletion`

1000

* `completion.ExampleLoginPrompt`

1001

1002

Looking ahead

1003

-------------

1004

1005

There are a number of people working on various branches -- some small feature

1006

extensions, and some major coverage additions that add signifant capabilies --

1007

but which haven't quite made it to the point where they can be merged into

1008

java-gnome. We'll see how these pieces of work fare in the coming months, but

1009

nevertheless the Java bindings for GNOME have reached a significant level of

1010

maturity and we are pleased to see people starting to use them in serious

1011

applications.

1012

1013

AfC

1014

1015

1016

1017

java-gnome 4.0.11 (1 May 2009)

1018

==============================

1019

1020

_This is a bug fix release._

1021

1022

We made a few mistakes in our handling of the PangoAttribute structures'

1023

memory which resulted in VM crashes [unfortunately, the normal GNOME way of

1024

debugging things is to `SIGSEGV`. That's fine for a C program but Bad™ for

1025

your average Java Virtual Machine as it takes out the entire process. We

1026

therefore work rather hard to avoid -- or at least trap -- this sort of

1027

thing]. Releasing corrections for these bugs was a priority.

1028

1029

Concurrently a significant internal improvement in our handling of

1030

accumulating Attributes into AttributeLists was made. While this is not user

1031

visible _per se_, we were able to drop the requirement that the text you were

1032

formatting already be in the Pango Layout before assigning the range that the

1033

Attribute would cover. You also no longer need to pass that Layout to

1034

`setIndices()`. This makes things a great deal easier if you are

1035

simultaneously aggregating the text and assigning markup.

1036

1037

* **`org.gnome.pango.Attribute`**

1038

* **`org.gnome.pango.AttributeList`**

1039

* `org.gnome.pango.PangoAttributeOverride`

1040

* **`org.gnome.pango.Layout`**

1041

* **`org.gnome.pango.FontDescription`**

1042

* **`org.gnome.pango.FallbackAttribute`**

1043

* `org.gnome.pango.ValidatePangoTextRendering`

1044

* **`org.gnome.pango.WrapMode`**

1045

1046

Martin Garton contributed some documentation quality improvements and new

1047

coverage. Serkan Kaba made some minor fixes to ensure the unit tests run in a

1048

Turkish locale. And as ever there are small incremental improvements to

1049

various classes, including a number of additional properties exposed care of

1050

the work of new contributor Thijs Leibbrand.

1051

1052

* **`org.gnome.gtk.TreeViewColumn`**

1053

* **`org.gnome.gtk.ComboBox`**

1054

* **`org.gnome.gtk.Widget`**

1055

* `org.freedesktop.bindings.ValidateInternationalization`

1056

* **`org.gnome.gtk.Label`**

1057

* **`org.gnome.gtk.ScrolledWindow`**

1058

* **`org.gnome.gtk.Box`**

1059

* **`org.gnome.gtk.AboutDialog`**

1060

1061

Looking ahead

1062

-------------

1063

1064

This was a brief cycle; as noted we're mostly pushing some bug fixes.

1065

Meanwhile there are a number of significant branches underway by various

1066

hackers; which, hopefully, will feature prominently in the next release.

1067

1068

AfC

1069

1070

1071

1072

java-gnome 4.0.10 (5 Mar 2009)

1073

==============================

1074

1075

_Sculptures made of letters_

1076

1077

This release is a landmark, because it features coverage of the Pango text

1078

rendering library and so, along with our coverage of Cairo, brings us to a

1079

complete solution for drawing graphics with text -- be they custom Widgets,

1080

PDF documents, or beautiful vector illustrations.

1081

1082

In addition to merging Pango work from numerous contributors, we have made

1083

massive improvements to our Cairo coverage, support for writing PDFs, and

1084

better access to the system Clipboard.

1085

1086

Drawing API improvements

1087

------------------------

1088

1089

We've done a huge amount of refinement to our APIs for the ever fabulous Cairo

1090

Graphics drawing library, including full coverage of matrix translations,

1091

rotations, and scaling and more integrated ways of setting the source pattern

1092

to be used in stroke, paint, and fill operations. <img

1093

src="doc/api/4.1/org/freedesktop/cairo/Matrix-translate.png" alt="" style="float:

1094

right; text-align: right; padding-left: 15px;" /> Thanks to Kenneth Prugh for

1095

having seen this through and having done the lion's share of the testing. <img

1096

src="doc/api/4.1/org/freedesktop/cairo/Context-arcNegative.png" alt=""

1097

style="float: right; text-align: right; padding-left: 15px; clear: right;" />

1098

1099

* **`org.freedesktop.cairo.Content`**

1100

* **`org.freedesktop.cairo.Context`**

1101

* **`org.freedesktop.cairo.Matrix`**

1102

* `org.freedesktop.cairo.Plumbing`

1103

* `org.freedesktop.cairo.Status`

1104

* **`org.freedesktop.cairo.Surface`**

1105

* **`org.freedesktop.cairo.ImageSurface`**

1106

* **`org.freedesktop.cairo.SvgSurface`**

1107

* **`org.freedesktop.cairo.XlibSurface`**

1108

* **`org.freedesktop.cairo.SurfacePattern`**

1109

* `cairo.ExampleDrawingText`

1110

1111

The various use cases of setting a source pattern for a Context including RGB,

1112

RGBA, other Surfaces, already existing Pixbufs, etc have been combined into a

1113

series of `setSource()` method overloads.

1114

1115

We've also had a number of improvements in the lower levels of GTK relating to

1116

image rendering. The gdk-pixbuf library contains a capable image parser and we

1117

can now feed it directly from a Pixbuf constructor. Thanks to new contributor

1118

Martin Garton for his hard work getting that tested and accepted.

1119

1120

* **`org.gnome.gdk.InterpType`**

1121

* **`org.gnome.gdk.Pixbuf`**

1122

1123

Drawing graphics often also requires drawing text. This release features

1124

coverage of Pango, GNOME's powerful text rendering library. Pango is not just

1125

about drawing mere glyphs; it also includes a sophisticated paragraph layout

1126

engine which gives us a capable solution for drawing text onto Cairo Surfaces.

1127

1128

Thanks are due to Serkan Kaba and Kenneth Prugh have both been really helpful

1129

testing; it was Vreixo Formoso who did the original leg work in April that

1130

identified Layout as the key class that we needed to concentrate on and

1131

cleaned up much of the underlying infrastructure.

1132

1133

* **`org.gnome.pango.Alignment`**

1134

* **`org.gnome.pango.FontDescription`**

1135

* **`org.gnome.pango.Layout`**

1136

* **`org.gnome.pango.LayoutLine`**

1137

* **`org.gnome.pango.Rectangle`**

1138

* **`org.gnome.pango.Style`**

1139

* **`org.gnome.pango.Variant`**

1140

* **`org.gnome.pango.Weight`**

1141

* `org.gnome.pango.Plumbing`

1142

* **`org.gnome.pango.Context`**

1143

* **`org.freedesktop.cairo.FontOptions`**

1144

* **`org.freedesktop.cairo.HintMetrics`**

1145

* **`org.gnome.pango.Attribute`**

1146

* **`org.gnome.pango.AttributeList`**

1147

* **`org.gnome.pango.FontDescriptionAttribute`**

1148

* **`org.gnome.pango.SizeAttribute`**

1149

* **`org.gnome.pango.StyleAttribute`**

1150

* **`org.gnome.pango.VariantAttribute`**

1151

* **`org.gnome.pango.WeightAttribute`**

1152

* **`org.gnome.pango.UnderlineAttribute`**

1153

* **`org.gnome.pango.BackgroundColorAttribute`**

1154

* **`org.gnome.pango.ForegroundColorAttribute`**

1155

* **`org.gnome.pango.BackgroundColorAttribute`**

1156

* **`org.gnome.pango.UnderlineColorAttribute`**

1157

1158

As we were working on this we had occasion to continue the polish in and

1159

around the TextView / TextBuffer APIs, including a number of convenience

1160

methods for inserting text while simultaneously applying multiple TextTags,

1161

and supporting changing default fonts.

1162

1163

* **`org.gnome.gtk.TextBuffer`**

1164

* **`org.gnome.gtk.TextIter`**

1165

* **`org.gnome.gtk.TextTag`**

1166

* **`org.gnome.gtk.TextView`**

1167

* **`org.gnome.gtk.TreeViewColumn`**

1168

* **`org.gnome.gtk.Widget`**

1169

1170

We've also modelled "notify signals" for when a property changes; see the

1171

`TextBuffer.NotifyCursorPosition` signal for this in action.

1172

1173

Finally, thanks to contributions from Zak Fenton and Kamil Szymala we have

1174

support for applications running in composited window managers to have

1175

transparent backgrounds -- which is an exceptionally cool effect, even if it

1176

doesn't have much to do with creating HIG compliant usable applications `:)`.

1177

1178

* **`org.freedesktop.cairo.Operator`**

1179

* **`org.gnome.gdk.Colormap`**

1180

* **`org.gnome.gdk.Screen`**

1181

* **`org.gnome.gdk.Window`**

1182

* **`org.gnome.gtk.Widget`**

1183

1184

Handling cut & paste

1185

--------------------

1186

1187

The GTK clipboard APIs are fairly complex, in no small part because the

1188

underlying implementations in X are really rather complex. Our coverage here

1189

in java-gnome is still fairly basic relative to that, but it's been enough for

1190

people working on applications like text editors to write text to the system

1191

clipboard, get notification when the clipboard changes, and read text back out

1192

again.

1193

1194

* **`org.gnome.gtk.Clipboard`**

1195

1196

Printed document support

1197

------------------------

1198

1199

<img src="doc/examples/cairo/ExampleLinedPaper.png" alt="" width="200"

1200

style="float: right; text-align: right; padding-left: 15px; clear: right;" />

1201

The work on Pango noted above represented the essential machinery necessary to

1202

make effective use of Cairo's PDF backend, and this has started us down the

1203

road of covering the GNOME printing APIs. You can now generate `.pdf`

1204

documents with java-gnome, and we've included an fun

1205

[example](doc/examples/START.html#ExampleLinedPaper) showing this in action.

1206

1207

* **`org.freedesktop.cairo.PdfSurface`**

1208

* **`org.gnome.gtk.PaperSize`**

1209

* **`org.gnome.gtk.InternationalPaperSize`**

1210

* **`org.gnome.gtk.NorthAmericanPaperSize`**

1211

* **`org.gnome.gtk.Unit`**

1212

* `cairo.ExampleLinedPaper`

1213

1214

Thanks to Nathan Strum for permission to use one of his sketches in the

1215

example (you might find reading the [blog][nathan] where we found this

1216

interesting -- it's a fascinating exposé of a graphic artist in action).

1217

1218

[nathan]: http://www.atariage.com/forums/index.php?automodule=blog&blogid=118&showentry=5460

1219

1220

Continuing improvement

1221

----------------------

1222

1223

Thanks to new contributor Stefan Schweizer we now have better coverage of

1224

signals relating to Notebook style Containers, and to new contributors Miloud

1225

Bel and Bruno Dusausoy for numerous small improvements in and around

1226

ProgressBar.

1227

1228

* **`org.gnome.gtk.Notebook`**

1229

* **`org.gnome.gtk.ProgressBar`**

1230

1231

Miscellaneous documentation improvements and minor feature improvements always

1232

feature in our releases, with minor changes having accrued in many classes.

1233

1234

* **`org.gnome.gtk.ShadowType`**

1235

* **`org.gnome.gdk.CrossingMode`**

1236

* **`org.gnome.gdk.NotifyType`**

1237

* **`org.gnome.gtk.AboutDialog`**

1238

* **`org.gnome.gtk.Arrow`**

1239

* **`org.gnome.gtk.ArrowType`**

1240

* **`org.gnome.gtk.Assistant`**

1241

* **`org.gnome.gtk.Menu`**

1242

1243

Just as important as new coverage is getting rid of cruft that we don't need.

1244

Libraries like GTK and GDK are, like any other mature project, full of

1245

deprecated, obsolete, and unnecessary code -- not to mention things that we

1246

just plain don't need in a Java binding of these underlying native libraries.

1247

We're already pretty good about not generating translation Java or JNI C code

1248

for such things; this release continues our refinements in this area with a

1249

considerable refinement of the `.jar` and `.so` which is ultimately what we

1250

ship.

1251

1252

Finally, it's worth noting that java-gnome's test suite is now 40 unit test

1253

classes with 186 individual test fixtures. Combined with over 30 screenshot

1254

generating programs and 17 example programs, we actually have surprisingly

1255

good test coverage of our library. It's high time they -- and more to the

1256

point the people who work hard to create such tests -- got as much credit as

1257

the visible public APIs do.

1258

1259

* `UnitTests`

1260

* `com.operationaldynamics.codegen.ValidateUtilityMethods`

1261

* `com.operationaldynamics.defsparser.ValidateBlockUsage`

1262

* `com.operationaldynamics.defsparser.ValidateDefsParsing`

1263

* `com.operationaldynamics.codegen.ValidateThingUsage`

1264

* `org.freedesktop.bindings.ValidateEnvironment`

1265

* `org.freedesktop.bindings.ValidateInternationalization`

1266

* `org.gnome.glib.ValidateReferenceCounting`

1267

* `org.gnome.glib.ValidateMemoryManagement`

1268

* `org.gnome.glib.ValidateGListMethods`

1269

* `org.gnome.glib.ValidateConstants`

1270

* `org.gnome.gtk.ValidateProperties`

1271

* `org.gnome.gtk.ValidateSignalEmission`

1272

* `org.gnome.gdk.ValidateScreensAndDisplays`

1273

* `org.gnome.gdk.ValidateKeyboardHandling`

1274

* `org.gnome.gdk.ValidateImageHandling`

1275

* `org.freedesktop.cairo.ValidateCairoInternals`

1276

* `org.freedesktop.cairo.ValidateDrawingToFile`

1277

* `org.gnome.gtk.ValidateOutParameters`

1278

* `org.gnome.gtk.ValidatePacking`

1279

* `org.gnome.gtk.ValidateNotebookBehaviour`

1280

* `org.gnome.gtk.ValidateFileChoosing`

1281

* `org.gnome.gtk.ValidateStockItems`

1282

* `org.gnome.gtk.ValidateResponseType`

1283

* `org.gnome.gtk.ValidateTreeModel`

1284

* `org.gnome.gtk.ValidateTreeStore`

1285

* `org.gnome.gtk.ValidateTreeModelFilter`

1286

* `org.gnome.gtk.ValidateTreeView`

1287

* `org.gnome.gtk.ValidateIconView`

1288

* `org.gnome.gtk.ValidateComboBox`

1289

* `org.gnome.gtk.ValidateSnapshotUtilities`

1290

* `org.gnome.gtk.ValidateAssistant`

1291

* `org.gnome.gtk.ValidateTextBuffer`

1292

* `org.gnome.gtk.ValidateTextViewProperties`

1293

* `org.gnome.gtk.ValidateTextViewBorderWindows`

1294

* `org.gnome.gtk.ValidateArrow`

1295

* `org.gnome.pango.ValidatePangoTextRendering`

1296

* `org.gnome.gtk.ValidatePrinting`

1297

* `Harness`

1298

* `org.freedesktop.cairo.SnapshotMatrixRotate`

1299

* `org.freedesktop.cairo.SnapshotCairoAxis`

1300

* `org.freedesktop.cairo.SnapshotCairo`

1301

* `org.freedesktop.cairo.SnapshotContextLine`

1302

* `org.freedesktop.cairo.SnapshotMatrixScale`

1303

* `org.freedesktop.cairo.SnapshotContextArcNegative`

1304

* `org.freedesktop.cairo.SnapshotMatrixTranslate`

1305

* `org.freedesktop.cairo.SnapshotContextArc`

1306

* `org.freedesktop.cairo.SnapshotMatrix`

1307

* `org.freedesktop.cairo.SnapshotContextRectangle`

1308

* `org.gnome.gtk.SnapshotCalendar`

1309

* `org.gnome.gtk.SnapshotTreeView`

1310

* `org.gnome.gtk.SnapshotButton`

1311

* `org.gnome.gtk.SnapshotAboutDialog`

1312

* `org.gnome.gtk.SnapshotArrow`

1313

* `org.gnome.gtk.SnapshotTextView`

1314

* `org.gnome.gtk.SnapshotRadioButton`

1315

* `org.gnome.gtk.SnapshotTextComboBox`

1316

* `org.gnome.gtk.SnapshotTreeStore`

1317

* `org.gnome.gtk.SnapshotTextComboBoxEntry`

1318

* `org.gnome.gtk.SnapshotFileChooserDialog`

1319

* `org.gnome.gtk.SnapshotTextViewBorderWindows`

1320

* `org.gnome.gtk.SnapshotVScale`

1321

* `org.gnome.gtk.SnapshotHScale`

1322

* `org.gnome.gtk.SnapshotDialog`

1323

* `org.gnome.gtk.SnapshotEntryRed`

1324

* `org.gnome.gtk.SnapshotComboBox`

1325

* `org.gnome.gtk.SnapshotStatusbar`

1326

* `org.gnome.gtk.SnapshotInfoMessageDialog`

1327

* `org.gnome.gtk.Snapshot`

1328

* `org.gnome.gtk.SnapshotAssistant`

1329

* `org.gnome.gtk.SnapshotWindow`

1330

* `org.gnome.gtk.SnapshotNotebook`

1331

* `org.gnome.gtk.SnapshotQuestionMessageDialog`

1332

1333

Anyone can run the tests (and anyone wanting to submit a patch had _better_

1334

run the tests!); they've been accumulating since java-gnome 4.0.0; it's just:

1335

1336

$ make test

1337

1338

and

1339

1340

$ make doc

1341

1342

If you're working in Eclipse launch class `UnitTests` as a JUnit test suite.

1343

1344

Build improvements

1345

------------------

1346

1347

We have some fixes from new contributor Przemysław Grzegorczyk ensuring we

1348

include the correct headers in a few corner cases. This came to us via work on

1349

a GNOME Love bug, which is a first for us. Thanks!

1350

1351

Meanwhile, the ever industrious Serkan Kaba has added some changes to ensure

1352

that our magically locating the native shared library component of java-gnome

1353

works properly even under strange and unusual conditions.

1354

1355

Configuration and prerequisite detection on Open Solaris is improved thanks to

1356

reports from new contributor Kamil Szymala.

1357

1358

Instructions for how to optimally lay out your branches when working with

1359

java-gnome have been moved to the [`HACKING`](HACKING.html) file. People

1360

intending to hack on the bindings from Eclipse are _really_ urged to set

1361

things up this way as it will make their lives much easier. Also, using the

1362

latest release of Bazaar (ie `bzr >= 1.12`) is definitely recommended -- it's

1363

getting really fast. We've upgraded our public branches, so you will need

1364

`1.9` at a minimum.

1365

1366

Note to those creating packages for distributions: java-gnome now depends on

1367

the current stable GTK (ie `gtk+ >= 2.14`).

1368

1369

Looking ahead

1370

-------------

1371

1372

Coverage of Poppler, GNOME's PDF rendering library is well along, but didn't

1373

quite make it in time for this release. It could very likely feature in the

1374

next version of java-gnome, as might coverage of GConf, GNOME's simple store

1375

for application configuration options. People are also known to be working on

1376

coverage of GtkSourceView, libwnck, and librsvg. We'll see what gets

1377

contributed!

1378

1379

The most exciting part about java-gnome at the moment, though, is the number

1380

of people working hard on applications using it. It takes a **long** time to

1381

write a mature, well rounded, robust end-user program, but there are some

1382

pretty cool projects ticking away out there, and it has been terrific to see

1383

the authors of these projects joining our community.

1384

1385

Happy developing,

1386

1387

AfC

1388

1389

1390

1391

Rendering text

1392

==============

1393

1394

One thing that was previously missing from our Cairo support was the ability

1395

to draw text. To that end we have been working on exposing the excellent Pango

1396

text rendering library. The '`pango`' branch where the effort has been

1397

underway to polish coverage allowing developers add text when drawing has now

1398

been merged to '`mainline`'.

1399

1400

Pango is not just about drawing mere words. It also includes a sophisticated

1401

paragraph layout engine. This in turn represents the essential machinery

1402

necessary to make effective use of Cairo's PDF backend; you can now generate

1403

`.pdf` documents with java-gnome, and we've included an fun example showing

1404

this in action.

1405

1406

Thanks are due to Serkan Kaba and Kenneth Prugh have both been really helpful

1407

testing; it was Vreixo Formoso who did the original leg work in April that

1408

identified Layout as the key class that we needed to concentrate on and

1409

cleaned up much of the underlying infrastructure.

1410

1411

The API documentation for [Layout][] is pretty much the center piece of all

1412

this work. Improvements to various Cairo backends have also been underway; the

1413

descriptions at [XlibSurface][] and [PdfSurface][] may also be of interest.

1414

1415

AfC

1416

1417

[Layout]: doc/api/4.1/org/gnome/pango/Layout.html

1418

[XlibSurface]: doc/api/4.1/org/freedesktop/cairo/XlibSurface.html

1419

[PdfSurface]: doc/api/4.1/org/freedesktop/cairo/PdfSurface.html

1420

1421

1422

1423

java-gnome 4.0.9 (13 Oct 2008)

1424

==============================

1425

1426

_The pen is mightier than the sword_

1427

1428

New coverage

1429

------------

1430

1431

<img src="doc/examples/textview/ExampleInstantMessenger.png" alt=""

1432

style="float: right; text-align: right; padding-left: 15px;" />

1433

1434

This is the first release with coverage of GTK's powerful TextView/TextBuffer

1435

multi-line text display and editing Widget. This has been the result of

1436

several months of careful effort to present a clean and self-consistent API

1437

while remaining faithful to the underlying implementation. This bulk of this

1438

work was done by Stefan Prelle and Andrew Cowie, with contributions from

1439

Kenneth Prugh and testing by many people in the `#java-gnome` community.

1440

1441

* **`org.gnome.gtk.TextBuffer`**

1442

* **`org.gnome.gtk.TextIter`**

1443

* **`org.gnome.gtk.TextTag`**

1444

* **`org.gnome.gtk.TextTagTable`**

1445

* **`org.gnome.gtk.TextView`**

1446

* **`org.gnome.gtk.TextWindowType`**

1447

1448

The snapshot at right is from

1449

[`ExampleInstantMessenger`](doc/examples/textview/ExampleInstantMessenger.html),

1450

included with the sources. It is a somewhat detailed example showing the use

1451

of TextView, TextBuffer, and related classes. Try running it!

1452

1453

Other improvements

1454

------------------

1455

1456

Continuous improvement to various classes, especially in our documentation.

1457

Incremental changes have occurred in a number of places. In the

1458

TreeView/TreeModel APIs, some useful methods for translating TreeIters from

1459

one model to another have been added.

1460

1461

* **`org.gnome.gtk.TreeModelSort`**

1462

* **`org.gnome.gtk.TreeModelFilter`**

1463

1464

Also thanks to the persistent work of Stefan Prelle, we have nice coverage of

1465

GTK's Assistant (aka druid, wizard, etc):

1466

1467

* **`org.gnome.gtk.Assistant`**

1468

1469

Better support for doing popup context menus, including some bug fixes. Thanks

1470

Srichand Pendyala for taking care of this and to Owen Taylor for having

1471

explained out some of the underlying implementation details.

1472

1473

* **`org.gnome.gdk.EventButton`**

1474

* **`org.gnome.gtk.Action`**

1475

* **`org.gnome.gtk.TreeView`**

1476

* **`org.gnome.gtk.Widget`**

1477

1478

And, as usual, incremental improvements to core classes, notably a few new

1479

signals here and there. Virtually every class has been touched in one way or

1480

another; most changes are cosmetic but they add up to significant

1481

contribution.

1482

1483

Reducing memory pressure

1484

------------------------

1485

1486

Internally, java-gnome maintains a lookup table so that pointers coming from

1487

the C side can be converted into proxy objects for the case where a proxy has

1488

already been created. In any library there a great number of transient and

1489

temporary objects and structures allocated, and we are no different. It turned

1490

out that registering these temporary objects was putting pressure on the

1491

lookup table. While these objects _were_ properly weak referenced and being

1492

garbage collected (and thence freed), there were nevertheless an enormous

1493

number of temporary objects being inserted and removed from the lookup table

1494

1495

To do something about this we have split the former hierarchy root into two

1496

classes. Only structures which have a persistent identity (which, in practise,

1497

means only GObjects and certain Cairo entities) are registered so they can be

1498

looked up by address later as necessary. These remain subclasses of the former

1499

root `Proxy`. The rest of the Java side proxies for are now subclasses of

1500

`Pointer` which is now the new root for our class hierarchy. These _aren't_

1501

registered, essentially eliminating the transient pressure on the lookup

1502

table.

1503

1504

* **`org.freedesktop.bindings.Pointer`**

1505

* **`org.freedesktop.bindings.Proxy`**

1506

* `org.freedesktop.bindings.Plumbing`

1507

* `org.freedesktop.cairo.Entity`

1508

* **`org.gnome.glib.Object`**

1509

* `org.gnome.glib.Plumbing`

1510

* **`org.gnome.glib.Boxed`**

1511

1512

This is entirely an internal change. Users of released & packaged versions of

1513

the library will not notice any difference. Developers and hackers who have a

1514

checkout of the project source code may need to `make clean` if they haven't

1515

since `'mainline'` revno 567.

1516

1517

Thanks to Vreixo Formoso for doing the bulk of the leg-work on this one.

1518

1519

Making it easier to run java-gnome programs

1520

-------------------------------------------

1521

1522

Because java-gnome is directly binds to underlying system libraries, it has a

1523

native shared library component. This led to the usual development hassle of

1524

having to specify where this library is to be found if it were anywhere other

1525

than `/usr` and of course the nightmare of ensuring a VM used the right

1526

library in the event you were developing against or hacking on a newer version

1527

of java-gnome; in Java this meant:

1528

1529

$ java -classpath /opt/local/share/java/gtk-4.0.jar:. -Djava.library.path=/opt/local/lib com.example.Program

1530

1531

No longer!

1532

1533

The native shared library part of java-gnome is now located deterministically

1534

and loaded automatically. You don't need to faff about with

1535

`java.library.path` on the command line or in your IDE any more!

1536

1537

$ java -classpath /opt/local/share/java/gtk-4.1.jar:. com.example.Program

1538

1539

Our native component is completely coupled to the specific release you are

1540

using, so sufficient version information is embedded in the `.so` name to

1541

ensure that the right library (and only the right library) is loaded.

1542

1543

There are _no_ changes if you are simply working against an "in-place"

1544

development build of java-gnome, be it from command line, or in an IDE like

1545

Eclipse, things will Just Work™; again, no `-Djava.library.path`:

1546

1547

$ java -classpath ~/workspace/java-gnome/tmp/gtk-4.1.jar:. com.example.Program

1548

1549

Note to downstream packagers: running `make install` is now **compulsory**.

1550

This signals a build that it is no longer being used "in-place" but instead is

1551

to be prepared for installation to a system prefix (Gentoo got bit by this;

1552

hooray for downstream packagers testing release candidates!). If you need to

1553

change the install locations, you can specify overrides when you run

1554

`./configure`, perhaps:

1555

1556

$ ./configure prefix=/usr jardir=/opt/share/java libdir=/usr/lib/jni

1557

1558

The defaults are all sensible, of course, and are as described in

1559

[README](README.html).

1560

1561

Build system improvements

1562

-------------------------

1563

1564

Serkan Kaba has contributed a number of internal improvements allowing the top

1565

level `./configure` script to be precise about the versions of various GNOME

1566

dependencies we require.

1567

1568

With the release of GTK 2.14, various bits of the underlying libraries have

1569

been deprecated. Thanks to the hard work from Serkan Kaba and new contributor

1570

George McLachlan, java-gnome correctly builds against GTK 2.14 without any

1571

problems.

1572

1573

Note that java-gnome releases do _not_ set `GTK_DISABLE_DEPRECATED` (this is a

1574

change from 4.0.8); thanks to Mart Raudsepp of the Gentoo Linux desktop team

1575

for pointing out why this would be better. These macros _are_ still enabled

1576

for builds checked out from version control so hackers working on the bindings

1577

so will be able to keep up with ensuring we react to future deprecations (it's

1578

always awesome when downstream is a part of the upstream community; Serkan and

1579

Kenneth are also Gentoo packagers, and take care of the java-gnome `.ebuild`

1580

for us).

1581

1582

Incidentally, the version constants identifying the library are now alongside

1583

the rest of the infrastructure. Public methods are now available if you want

1584

to use the API or release version number in a snapshot or example.

1585

1586

* **`org.freedesktop.bindings.Version`**

1587

1588

Looking ahead

1589

-------------

1590

1591

We're pretty happy with the state of the java-gnome right now. Coverage of the

1592

most important parts of GTK are in place. Our treatment of the underlying

1593

drawing library, Cairo, still has a bit to go, but the basics are there and a

1594

firm foundation to build from. More interesting are the remaining areas; the

1595

more general GNOME utility libraries and other parts of the Free Desktop stack

1596

that might be needed by an end-user application. It'll be interesting to see

1597

how these areas evolve in the coming months.

1598

1599

AfC

1600

1601

1602

1603

Lorem ipsum

1604

===========

1605

1606

A major concentration of effort over the last few months has been to write

1607

appropriate public coverage to present GTK's powerful but complex

1608

TextView/TextBuffer API, a Widget for presenting multi-line text and the

1609

backing store for manipulating it.

1610

1611

The '`textview`' branch where this work has been taking place has finally been

1612

merged to '`mainline`'.

1613

1614

As this development cycle continues we will continue to review and refine the

1615

API we're presenting, but this is nonetheless a significant milestone and one

1616

we're justly proud of. Thanks to Stefan Prelle for having done much of the leg

1617

work and also to Kenneth Prugh for his support during testing.

1618

1619

You can read the API documentation for [TextBuffer][] and [TextView][] if

1620

you're interested in how things are shaping up.

1621

1622

AfC

1623

1624

[TextBuffer]: doc/api/4.1/org/gnome/gtk/TextBuffer.html

1625

[TextView]: doc/api/4.1/org/gnome/gtk/TextView.html

1626

1627

1628

1629

java-gnome 4.0.8 (15 Aug 2008)

1630

==============================

1631

1632

_Cleanups and fixups._

1633

1634

This release is mostly to push out bug fixes and internal improvements,

1635

setting the stage for some major new feature development. We've also taken the

1636

opportunity to introduce a major change to the way we connect handlers for

1637

signals.

1638

1639

New coverage and continuing improvement

1640

---------------------------------------

1641

1642

With thanks to new contributors Stefan Prelle and Andreas Kuehntopf we have a

1643

number of small improvements to the TreeView/TreeModel APIs.

1644

1645

* **`org.gnome.gtk.TreeView`**

1646

* **`org.gnome.gtk.TreeViewColumn`**

1647

* **`org.gnome.gtk.TreeViewColumnSizing`**

1648

* **`org.gnome.gtk.CellRendererText`**

1649

* **`org.gnome.gtk.CellRendererToggle`**

1650

1651

As always, Widget and Window saw a bunch of work, with `Window.ConfigureEvent`

1652

now being available and a number of additional property setters and methods

1653

relating to window type.

1654

1655

* **`org.gnome.gdk.WindowTypeHint`**

1656

* **`org.gnome.gtk.Widget`**

1657

* **`org.gnome.gtk.Window`**

1658

1659

Widgets that scroll around a view of a broader underlying canvas have seen a

1660

fair bit of activity related to controlling that scrolling.

1661

1662

* **`org.gnome.gtk.Adjustment`**

1663

* **`org.gnome.gtk.Layout`**

1664

* **`org.gnome.gtk.ScrolledWindow`**

1665

* **`org.gnome.gtk.Viewport`**

1666

1667

New features include refinements and new coverage of methods in a variety of

1668

lower level classes including that further support drawing operations. Bug

1669

fixes, debugging improvements, and defencive enhancements to our thread safety

1670

measures have also featured largely.

1671

1672

* `org.freedesktop.bindings.Plumbing`

1673

* `org.gnome.glib.GObject`

1674

* **`org.gnome.glib.Object`**

1675

* `org.gnome.glib.Plumbing`

1676

* `org.gnome.gdk.Plumbing`

1677

* **`org.gnome.gdk.Rectangle`**

1678

* **`org.gnome.gdk.Pixbuf`**

1679

* **`org.gnome.gdk.Window`**

1680

* **`org.gnome.gtk.Allocation`**

1681

* **`org.gnome.gtk.Box`**

1682

* **`org.gnome.gtk.Button`**

1683

* **`org.gnome.gtk.Entry`**

1684

* **`org.gnome.gtk.Image`**

1685

* **`org.gnome.gtk.IconView`**

1686

* **`org.gnome.gtk.Gtk`**

1687

* **`org.gnome.gtk.Requisition`**

1688

* **`org.gnome.gtk.Table`**

1689

1690

Signal naming change

1691

--------------------

1692

1693

We have changed the naming scheme used to name the interfaces that are used

1694

when hooking up signal handlers.

1695

1696

The names of the inner interfaces used to specify the prototypes of the

1697

methods which receive signal callbacks have changed to the pattern

1698

`Button.Clicked`, this being more appropriate to Java type naming conventions

1699

and providing better consistency between the signal name, the method to be

1700

implemented to receive the callback, and the method that can be used to emit

1701

this signal.

1702

1703

API compatibility to previous releases in the 4.0 series has been preserved.

1704

The old signal interfaces and `connect()` methods are `@deprecated`.

1705

Developers are encouraged to migrate quickly; new coverage will of course all

1706

follow the new pattern. Making the transition is is easy, especially in an

1707

IDE. Most of the people we're aware of using the library have already ported

1708

their code. Just turn assertions on to double check.

1709

1710

Build changes

1711

-------------

1712

1713

java-gnome now defines C compiler flags like `GTK_DISABLE_DEPRECATED` to

1714

ensure we are not linking against code that will be unavailable in GTK 3.0.

1715

Many thanks are due to new contributor Kenneth Prugh for having done some

1716

terrific grunt work to prune deprecated classes and methods from our `.defs`

1717

data so that java-gnome compiles without using these APIs.

1718

1719

The build system internally now ensures that multiple runs don't occur

1720

simultaneously, fixing a number of annoyances that cropped up when using IDEs

1721

which tend to like trying to frequently re-run the build even if a previous

1722

one hasn't finished.

1723

1724

Documentation, examples, and testing

1725

------------------------------------

1726

1727

Our [API documentation](doc/api/4.1/overview-summary.html) and the growing set of

1728

[example code](doc/examples/START.html) have all been updated to reflect the

1729

new signal interface names. Doing so forced us to review a wide swath of the

1730

documentation, and so along the way a huge number of minor improvements were

1731

made. Given how detailed our JavaDoc is, this sort of painstaking work really

1732

makes a genuine contribution to overall quality.

1733

1734

There has been steady growth in our test suite, which is great. When combined

1735

with the snapshots used to illustrate our documentation, the coverage level

1736

is substantial.

1737

1738

Error handling continues to improve. In the (hand written) public API wrapper

1739

layer we do our best to catch misuses of the library before they get sent to

1740

the native code. But that's not always possible, and in 4.0.7 we introduced a

1741

mechanism whereby GLib error messages get translated into Java Exceptions and

1742

thrown. As of 4.0.8, in addition to `ERROR` and `CRITICAL`, we also throw

1743

`WARNING`s as Exceptions. Getting a stack trace this way has proved very

1744

useful in helping developers track down where they are making mistakes in

1745

using the library.

1746

1747

Conclusion

1748

----------

1749

1750

You can see the full changes accompanying a release by grabbing a copy of the

1751

sources and running:

1752

1753

$ bzr diff -r tag:v4.0.7..tag:v4.0.8

1754

1755

Because of the API changes to signal handling this release touches just about

1756

every public class in the library and so isn't quite as clean (as a summary)

1757

as in previous releases -- but it does show you everything that changed. `:)`

1758

1759

Looking ahead

1760

-------------

1761

1762

Most of the contributors to java-gnome are working on branches that didn't

1763

reach sufficient maturity to be merged in time for 4.0.8; that's the way it

1764

goes sometimes. Major effort continues on implementing coverage of GTK's

1765

powerful TextView/TextBuffer APIs, along with further drawing capabilities in

1766

Cairo and Pango. There have also been a surprising level of interest on other

1767

areas of the GNOME stack, with new contributors working on adding support to

1768

java-gnome for Nautilus, GStreamer, and even WebKit. Exciting stuff!

1769

1770

AfC

1771

1772

1773

1774

Signal API change

1775

=================

1776

1777

We have changed the naming scheme used to name the interfaces that are used

1778

when hooking up signal handlers.

1779

1780

Connecting a handler to a Button now looks as follows:

1781

1782

1783

b.connect(new Button.Clicked() {

1784

public void onClicked(Button source) {

1785

// do stuff

1786

}

1787

});

1788

</pre>

1789

1790

Those developing with java-gnome will recognize that the inner interface's

1791

name has changed to `Button.Clicked`, being more appropriate to Java type

1792

naming conventions and providing better consistency between the signal name,

1793

the method to be implemented, `onClicked()`, and the method that can be used

1794

to emit this signal, `emitClicked()`.

1795

1796

The process which led to this change was discussed on the `java-gnome-hackers`

1797

mailing list; see first [message][] if interested.

1798

1799

[message]: http://article.gmane.org/gmane.comp.gnome.bindings.java.devel/1147

1800

1801

Interfaces with the old names and corresponding `connect()` methods are still

1802

present in the library (marked `@deprecated`, of course, and with assertions

1803

to encourage developers to migrate their code) so the upcoming release will

1804

preserve ABI compatibility.

1805

1806

The [documentation](doc/api/4.1/overview-summary.html) posted here has been

1807

updated and a release candidate has been uploaded.

1808

1809

AfC

1810

1811

1812

1813

java-gnome 4.0.7 (30 Apr 2008)

1814

==============================

1815

1816

_Draw some._

1817

1818

In addition to improvements to our coverage of the GNOME libraries, this

1819

release introduces preliminary coverage of the Cairo Graphics drawing library,

1820

along with the infrastructure to make it work within a GTK program.

1821

1822

Drawing with Cairo

1823

------------------

1824

1825

![Example](doc/examples/cairo/ExampleCairoDrawingBlends.png)

1826

1827

The trusty Cairo context, traditionally declared as a variable named `cr` in

1828

code, is mapped as class

1829

[`Context`](doc/api/4.1/org/freedesktop/cairo/Context.html). Various Cairo types

1830

such as different surfaces and patterns are mapped as an abstract base class

1831

(`Surface`, `Pattern`) along with various concrete subclasses (`ImageSurface`,

1832

`XlibSurface`, and `SolidPattern`, `RadialPattern`, etc). Error checking is

1833

implicit: the library status is checked internally after each operation and an

1834

Exception thrown if there is a failure.

1835

1836

* `org.freedesktop.cairo.Plumbing`

1837

* **`org.freedesktop.cairo.Context`**

1838

* **`org.freedesktop.cairo.ImageSurface`**

1839

* **`org.freedesktop.cairo.XlibSurface`**

1840

* **`org.freedesktop.cairo.SVGSurface`**

1841

* **`org.freedesktop.cairo.SolidPattern`**

1842

* **`org.freedesktop.cairo.LinearPattern`**

1843

* **`org.freedesktop.cairo.RadialPattern`**

1844

* **`org.freedesktop.cairo.SurfacePattern`**

1845

* **`org.freedesktop.cairo.Operator`**

1846

* **`org.freedesktop.cairo.Format`**

1847

* `org.freedesktop.cairo.Status`

1848

* `org.freedesktop.bindings.FatalError`

1849

* **`org.freedesktop.cairo.FatalError`**

1850

1851

The gateway to custom Widgets is the

1852

[`EXPOSE_EVENT`](doc/api/4.1/org/gnome/gtk/Widget.EXPOSE_EVENT.html) signal; this

1853

is where you can transition from the GDK `Window` to a Cairo `Context` and

1854

then begin drawing.

1855

1856

* **`org.gnome.gtk.Widget.EXPOSE_EVENT`**

1857

* **`org.gnome.gdk.EventExpose`**

1858

* **`org.gnome.gdk.Rectangle`**

1859

* **`org.gnome.gdk.EventCrossing`**

1860

* **`org.gnome.gdk.CrossingMode`**

1861

* **`org.gnome.gdk.NotifyType`**

1862

* **`org.gnome.gtk.Image`**

1863

1864

Thanks in particular to Carl Worth for having reviewed our API and having

1865

helped test our implementation.

1866

1867

New coverage and continuing improvement

1868

---------------------------------------

1869

1870

The single option choice buttons in GTK are called `RadioButton`s and have now

1871

been exposed. When using them you need to indicate the other buttons they are

1872

sharing a mutually exclusive relationship with, and this is expressed by

1873

adding them to a `RadioButtonGroup`.

1874

1875

![RadioButton](doc/api/4.1/org/gnome/gtk/RadioButton.png)

1876

1877

1878

* **`org.gnome.gtk.RadioButton`**

1879

* **`org.gnome.gtk.RadioButtonGroup`**

1880

1881

The usual steady refinements to our coverage of the GtkTreeView API continue.

1882

There's a new `DataColumn` type for Stock icons, and TreeModelSort is now

1883

implemented.

1884

1885

* **`org.gnome.gtk.TreeModelSort`**

1886

* **`org.gnome.gtk.DataColumnPixbuf`**

1887

* **`org.gnome.gtk.DataColumnStock`**

1888

* **`org.gnome.gtk.CellRendererPixbuf`**

1889

* **`org.gnome.gtk.TreeView`**

1890

* **`org.gnome.gtk.TreeModel`**

1891

* **`org.gnome.gtk.ListStore`**

1892

* **`org.gnome.gtk.TreeStore`**

1893

1894

and minor changes to various other miscellaneous classes:

1895

1896

* **`org.freedesktop.bindings.Environment`**

1897

* **`org.gnome.gtk.Expander`**

1898

* **`org.gnome.gtk.Frame`**

1899

* **`org.gnome.gtk.Paned`**

1900

* **`org.gnome.gtk.HPaned`**

1901

* **`org.gnome.gtk.VPaned`**

1902

* **`org.gnome.gtk.Widget`**

1903

* **`org.gnome.gtk.ProgressBar`**

1904

* **`org.gnome.gtk.Action`**

1905

1906

Considerable internal optimizations have been done, especially relating to

1907

ensuring proper memory management, with notable refinements to make use of

1908

"caller owns return" information available in the `.defs` data. This fixes a

1909

number of bugs. Thanks to Vreixo Formoso for having driven these improvements.

1910

1911

Error handling has been improved for GLib based libraries as well. If an

1912

`ERROR` or `CRITICAL` is emitted, our internals will trap this and throw an

1913

exception instead, allowing the developer to see a Java stack trace leading

1914

them to the point in their code where they caused the problem.

1915

1916

* **`org.gnome.glib.FatalError`**

1917

1918

Internationalization support

1919

----------------------------

1920

1921

java-gnome now has full support for the GNOME translation and localization

1922

infrastructure, including the standard `_("Hello")` idiom for marking strings

1923

for extraction and translation. There's a fairly detailed explanation in the

1924

[`Internationalization`](doc/api/4.1/org/freedesktop/bindings/Internationalization.html)

1925

utility class.

1926

1927

* **`org.freedesktop.bindings.Internationalization`**

1928

1929

Build changes

1930

-------------

1931

1932

Note that as was advertised as forthcoming some time ago, Java 1.5 is now the

1933

minimum language level required of your tool chain and Java virtual machine in

1934

order to build and use the java-gnome library.

1935

1936

Thanks to Colin Walters, Manu Mahajan, Thomas Girard, Rob Taylor, and Serkan

1937

Kaba for contributing improvements allowing the library to build in more

1938

environments and for their work on packages for their distributions.

1939

1940

The [download](get/) page has updated instructions for getting either binary

1941

packages or checking out the source code.

1942

1943

Documentation, examples, and testing

1944

------------------------------------

1945

1946

Refinements to the API documentation continue across the board, notably

1947

improving consistency. A large number of javadoc warnings have also been

1948

cleaned up.

1949

1950

While not a full blown tutorial, the number of fully explained examples is

1951

growing. There are examples for box packing and signal connection, presenting

1952

tabular data, and basic drawing, among others. See the description page in the

1953

[`doc/examples/`](doc/examples/START.html) section.

1954

1955

This code, together with the not inconsiderable number of unit tests and the

1956

code for generating snapshots of Widgets and Windows means that a large

1957

portion of the public API is tested within the library itself. The number of

1958

non-trivial applications making use of java-gnome is starting to grow, which

1959

are likewise providing for ongoing validation of the codebase.

1960

1961

Summary

1962

-------

1963

1964

You can see the full changes accompanying a release by grabbing a copy of the

1965

sources and running:

1966

1967

$ bzr diff -r tag:v4.0.6..tag:v4.0.7

1968

1969

Looking ahead

1970

-------------

1971

1972

It's probably unwise to predict what will be in future releases. The challenge

1973

for anyone contributing is that they need to understand _what_ something does,

1974

_when_ to use it (and more to the point, when not to!), and be able to

1975

_explain_ it to others. This needs neither prior experience developing with

1976

GNOME or guru level Java knowledge, but a certain willingness to dig into

1977

details _is_ necessary.

1978

1979

That said, I imagine we'll likely see further Cairo improvements as people

1980

start to use it in anger. It shouldn't take too long until the bulk of the

1981

functionality needed for most uses is present in java-gnome. In particular,

1982

forthcoming coverage of the Pango text drawing library will round things out

1983

nicely.

1984

1985

There are a number of other major feature improvements we'd like to see in

1986

java-gnome. Conceptual and design work is ongoing on for bindings of GConf,

1987

GStreamer, and even support for applets. Within GTK, there have been a number

1988

of requests made for various things to be exposed, for example, the powerful

1989

GtkTextView / GtkTextBuffer text display and editing capability. Some of these

1990

have preliminary implementations; whether or not any given piece of work is

1991

acceptable in time for any particular future release will remain to be seen

1992

and depends on the willingness of clients to fund us to review and test such

1993

work.

1994

1995

In the mean time, people are happily _using_ the library to develop rich user

1996

interfaces, which is, of course, the whole point. We're always pleased to

1997

welcome new faces to the community around the project. If you want to learn

1998

more, stop by `#java-gnome` and say hello!

1999

2000

AfC

2001

2002

2003

2004

Debian packages

2005

===============

2006

2007

The java-gnome bindings suite is now available in [Debian

2008

Linux](http://www.debian.org/) as

2009

2010

* `libjava-gnome-java`

2011

2012

If you need help installing it, see the the Debian page in the

2013

[download](/get/debian.php) section here.

2014

2015

Compliments to Manu Mahajan for having done the research to develop the Debian

2016

package, and thanks to Thomas Girard for having refined Manu's start and for

2017

having seen through the process of getting the package uploaded.

2018

2019

AfC

2020

2021

2022

2023

Cairo support

2024

=============

2025

2026

Adding coverage of the Cairo Graphics library is a feature we've been working

2027

on for about 6 months now, and during the 4.0.7 development cycle we've been

2028

able to land it in java-gnome!

2029

2030

Cairo is a huge library, of course, but we've put enough coverage in place to

2031

ensure that things are working. Cairo has lots of convenience functions and

2032

tons of obscure uses; no surprise (and no apology) that there's still lots

2033

that will need doing. If you want to help make sure it has what you need, then

2034

grab '`mainline`' and see `org.freedesktop.cairo.`[`Context`][Context].

2035

2036

Huge thanks go out to Behdad Esfahbod and Carl Worth; Behdad was really

2037

critical in explaining some basic Cairo concepts to me started when we were

2038

working together at the GNOME Summit back in October in Boston, and during March

2039

at the GTK hackfest in Berlin, Carl Worth was awesome for having checked our

2040

preliminary APIs and for having helped sorted us out as we were working our

2041

way through create some examples.

2042

2043

[Context]: doc/api/4.1/org/freedesktop/cairo/Context.html

2044

2045

AfC

2046

2047

2048

2049

java-gnome 4.0.6 (12 Feb 2008)

2050

==============================

2051

2052

_Finding the missing methods._

2053

2054

Most of our effort recently has simply been fleshing out areas of the

2055

public API. The focus for this work as been getting the coverage needed to

2056

allow us to port some of our in-house applications to java-gnome 4.0. It's not

2057

especially glamorous -- if anything it has been tedious as hell -- but the

2058

result has been a large body of improvements to java-gnome as a whole which

2059

we're pleased to release as java-gnome 4.0.6

2060

2061

The bulk of this development took place on the '`missing`' branch, so named

2062

because that's where I was working on what was missing `:)`.

2063

2064

Continuing Improvement

2065

----------------------

2066

2067

Notable public changes include coverage additions to enable key stroke and

2068

mouse button handling:

2069

2070

* **`org.gnome.gdk.Keyval`**

2071

* **`org.gnome.gdk.KeypadKeyval`**

2072

* **`org.gnome.gdk.EventKey`**

2073

* **`org.gnome.gdk.ModifierType`**

2074

* **`org.gnome.gdk.MouseButton`**

2075

* **`org.gnome.gdk.EventButton`**

2076

2077

Rather than exposing the `int` keyvals that bubble up out of the X server, we

2078

have wrapped these as constants of type

2079

[Keyval](doc/api/4.1/org/gnome/gdk/Keyval.html) (thereby being consistent with the

2080

rest of java-gnome in our working to the strengths of Java as a strongly-typed

2081

language; MouseButton was created for the same reason, helping developers

2082

understand just what on earth mouse button

2083

"[1](doc/api/4.1/org/gnome/gdk/MouseButton#LEFT)" is, anyway). Along with

2084

[ModifierType](doc/api/4.1/org/gnome/gdk/ModifierType.html), this gives enough to

2085

deal with the `KEY_PRESS_EVENT` and `KEY_RELEASE_EVENT` signals when the

2086

developer wishes to deal with key strokes.

2087

2088

We've finally gotten around to providing proper coverage of the box packing

2089

model which underlies every aspect of how GTK presents user interfaces. To

2090

understand the size-request/size-allocation process, you might start with

2091

Widget's

2092

[`setSizeRequest()`](doc/api/4.1/org/gnome/gtk/Widget.html#setSizeRequest$int,%20int$).

2093

2094

* **`org.gnome.gtk.Requisition`**

2095

* **`org.gnome.gtk.Allocation`**

2096

* **`org.gnome.gtk.Widget`**

2097

* **`org.gnome.gtk.Container`**

2098

* **`org.gnome.gtk.SizeGroup`**

2099

* **`org.gnome.gtk.SizeGroupMode`**

2100

2101

We've also added coverage for SizeGroup, which, when used in concert with

2102

nested VBoxes and HBoxes, can work wonderful magic and is often far better

2103

than messing around with Table when doing complex layouts.

2104

2105

After dithering for several releases, we've settled on how we're going to deal

2106

with ComboBox and family. The underlying GtkComboBox presents something of a

2107

nightmare as it is really two classes in one with more-or-less incompatible

2108

APIs. So, not surprisingly, we've presented it as two sets of classes, with the

2109

text-only convenience API spliced out of ComboBox and ComboBoxEntry into

2110

TextComboBox and TextComboBoxEntry respectively.

2111

2112

* **`org.gnome.gtk.ComboBox`**

2113

* **`org.gnome.gtk.ComboBoxEntry`**

2114

* **`org.gnome.gtk.TextComboBox`**

2115

* **`org.gnome.gtk.TextComboBoxEntry`**

2116

2117

We've added a few new features in our coverage of GTK's TreeView API, and many

2118

other classes involved have also seen improvements. The persistent reference to

2119

a row provided by TreeRowReference is now available as is model type

2120

TreeModelFilter.

2121

2122

* **`org.gnome.gtk.TreeModel`**

2123

* **`org.gnome.gtk.ListStore`**

2124

* **`org.gnome.gtk.TreeIter`**

2125

* **`org.gnome.gtk.TreePath`**

2126

* **`org.gnome.gtk.TreeView`**

2127

* **`org.gnome.gtk.TreeViewColumn`**

2128

* **`org.gnome.gtk.TreeViewColumnSizing`**

2129

* **`org.gnome.gtk.TreeModelFilter`**

2130

* **`org.gnome.gtk.TreeRowReference`**

2131

* **`org.gnome.gtk.CellLayout`**

2132

* **`org.gnome.gtk.CellRenderer`**

2133

* **`org.gnome.gtk.CellRendererPixbuf`**

2134

* **`org.gnome.gtk.CellRendererText`**

2135

2136

Support for the actual filtering in TreeModelFilter is notable for having been

2137

quite tricky. The underlying C library use a function pointers rather than a

2138

GObject signal emission, and we don't have any mechanism to handle that. We

2139

_do_, however, have a fantastic capability to marshal signals, so we dealt with

2140

the problem by creating a custom signal and then passing a function which emits

2141

it when the TreeModelFilter wants to ask the developer whether to include a row

2142

or not.

2143

2144

The new classes include support for TreeModel columns storing `long` data as

2145

well as setting properties of that type:

2146

2147

* `org.gnome.glib.Value`

2148

* `org.gnome.gtk.Value`

2149

* `org.gnome.gtk.Object`

2150

* **`org.gnome.gtk.DataColumnLong`**

2151

2152

It should also be noted that most of the methods taking a TreeViewColumn have

2153

been converted to taking an argument of type CellLayout (an interface

2154

implemented by TreeViewColumn). This has no change to how you use our TreeView

2155

API, but was necessary to support ComboBox properly.

2156

2157

Finally lots and lots of minor additions to both public APIs and internals

2158

deeper down in the GDK part of the toolkit:

2159

2160

* **`org.gnome.gdk.Color`**

2161

* **`org.gnome.gdk.Cursor`**

2162

* **`org.gnome.gdk.CursorType`**

2163

* **`org.gnome.gdk.Pixbuf`**

2164

* **`org.gnome.gdk.Window`**

2165

* **`org.gnome.gtk.AboutDialog`**

2166

* **`org.gnome.gtk.Action`**

2167

* **`org.gnome.gtk.Box`**

2168

* **`org.gnome.gtk.Button`**

2169

* **`org.gnome.gtk.Calendar`**

2170

* **`org.gnome.gtk.Editable`**

2171

* **`org.gnome.gtk.Entry`**

2172

* **`org.gnome.gtk.EventBox`**

2173

* **`org.gnome.gtk.Image`**

2174

* **`org.gnome.gtk.IconSize`**

2175

* **`org.gnome.gtk.ImageMenuItem`**

2176

* **`org.gnome.gtk.Label`**

2177

* **`org.gnome.gtk.ScrolledWindow`**

2178

* **`org.gnome.gtk.Statusbar`**

2179

* **`org.gnome.gtk.Table`**

2180

* **`org.gnome.gtk.Window`**

2181

2182

As ever, you can see the full changes accompanying a release by

2183

grabbing a copy of the sources and running:

2184

2185

$ bzr diff -r tag:v4.0.5..tag:v4.0.6

2186

2187

Documentation

2188

-------------

2189

2190

We've always had HTML JavaDoc for the current stable release at

2191

[`doc/api/`](doc/api/4.1/overview-summary.html) on the java-gnome website.

2192

We're going to change that a bit, though. As fixes to the explanatory

2193

documentation happen quite frequently to classes and methods all over the

2194

place, we've decided to generate the JavaDoc from '`mainline`' periodically and

2195

upload that instead. This means that there will, of course, be descriptions of

2196

some methods which aren't yet available in a released version of the library,

2197

but they will clearly identifiable by virtue of having a `@since` tag showing

2198

a version number greater than the most recent release.

2199

2200

The idea of having up-to-date illustrations of the various Widgets has proved

2201

popular, and we've continued to update the suite of snapshots. Doing that

2202

is _also_ tedious, but it does provide a good opportunity to test APIs we are

2203

exposing especially where unit tests are less suitable.

2204

2205

![Statusbar](doc/api/4.1/org/gnome/gtk/Statusbar.png)

2206

2207

Looking ahead

2208

-------------

2209

2210

Almost as complex as the TreeView/TreeModel API are GTK's powerful

2211

TextView/TextModel classes, collectively a Widget used to display and edit

2212

large text documents. Working out the java-gnome coverage for TextView will

2213

take a fair bit of consideration, but TreeView provides a road map, and, as

2214

with the coverage in 4.0.5 and 4.0.6 (which was driven largely by existing

2215

applications we were porting), we have some significant uses of GtkTextView

2216

which will guide us on our way.

2217

2218

The next release will also feature significant work outside of GTK; we should

2219

be in a position to merge our coverage of the excellent Cairo drawing library

2220

soon, and likewise we have tentative work in place letting people store

2221

configuration and settings data in GConf. Both the '`cairo`' and '`gconf`'

2222

branches need more QA and documentation work, but they're looking good and will

2223

definitely be featured in java-gnome 4.0.7.

2224

2225

AfC

2226

2227

2228

2229

java-gnome 4.0.5 (26 Nov 2007)

2230

==============================

2231

2232

_TreeView is here!_

2233

2234

It's always a great feeling when you bag a milestone, and with this release we

2235

have reached a major goal on our way to having outstanding Java bindings for

2236

the GNOME platform: coverage of GTK's powerful yet complex TreeView &

2237

TreeModel API.

2238

2239

TreeView

2240

--------

2241

2242

TreeViews are a central part of almost every application. GUIs use lists for

2243

all sorts of things, and so a significant goal was to make coding TreeViews

2244

and their backing TreeModels as straight forward as possible.

2245

2246

The most challenging and complex part was to design the Java side API, which

2247

was no small matter. As a native library, the GtkTreeView API is complex and

2248

very much written with programming in the C language in mind, and as such our

2249

algorithmic mapping of the underlying libraries into Java doesn't entirely

2250

fit. Long experience with the TreeViews in the previous bindings had made it

2251

clear just how nasty to use the API could be, and so the hardest part of the

2252

work was to come up with a mapping and a usage pattern that would be both

2253

faithful to GTK _and_ be sensible to use.

2254

2255

The other significant challenge was to document the work effectively. Our Java

2256

side API documentation is a major feature of java-gnome, and merely exposing

2257

classes and methods is not sufficient; they need to be clearly explained in

2258

our JavaDoc as well. Introduced in this release, then, are:

2259

2260

* **`org.gnome.gtk.TreeView`**

2261

* **`org.gnome.gtk.TreeViewColumn`**

2262

* **`org.gnome.gtk.CellRenderer`**

2263

* **`org.gnome.gtk.CellRendererText`**

2264

* **`org.gnome.gtk.CellRendererPixbuf`**

2265

* **`org.gnome.gtk.TreeSelection`**

2266

* **`org.gnome.gtk.SelectionMode`**

2267

* **`org.gnome.gtk.TreeModel`**

2268

* **`org.gnome.gtk.ListStore`**

2269

* **`org.gnome.gtk.TreeIter`**

2270

* **`org.gnome.gtk.TreePath`**

2271

* **`org.gnome.gtk.Alignment`**

2272

2273

along with numerous test cases in our unit test suite, and several

2274

comprehensively worked [examples][example-treeview].

2275

2276

This was a monster patch, and the culmination of not just three months direct

2277

effort, but also where we've been heading since we first started the

2278

re-engineering of Java bindings for GNOME. Although largely written by Andrew

2279

Cowie, a _significant_ contribution was made by Srichand Pendyala who not only

2280

exhaustively evaluated the design but also threw in some serious chunks of

2281

code. The work benefited from comprehensive input from Peter Miller on the

2282

modelling and design, and the comments of Bryan Clark, Owen Taylor, and Hanna

2283

Wallach were all really positive and helped us know that we'd gone in the

2284

right direction. Finally, thanks to Behdad Esfahbod and the GNOME Foundation

2285

who made it possible for us to meet in Boston at the GNOME Summit and so

2286

accomplish much of the final pulling together of this branch.

2287

2288

Continuing Improvement

2289

----------------------

2290

2291

Meanwhile, steady work continues on to the fundamental base classes, with a

2292

whack of additional signals and methods on Widget and especially Window, along

2293

with expansion of coverage in numerous other classes:

2294

2295

* **`org.gnome.gtk.Widget`**

2296

* **`org.gnome.gtk.Window`**

2297

* **`org.gnome.gtk.StateType`**

2298

* **`org.gnome.gdk.Color`**

2299

* **`org.gnome.gdk.VisibilityState`**

2300

* **`org.gnome.gdk.EventVisibility`**

2301

2302

What else? We've begun to get the basics of image handling in place,

2303

2304

* **`org.gnome.gdk.Pixbuf`**

2305

* **`org.gnome.gtk.Image`**

2306

* **`org.gnome.gtk.ImageMenuItem`**

2307

2308

One nice piece of contributed work came from Vreixo Formoso and Thomas Schmitz

2309

with coverage of the Dialog Window functionality in GTK. It took a bit of

2310

doing to map the `int` response codes used by GTK into something suitably

2311

strongly-typed, but all good:

2312

2313

* **`org.gnome.gtk.Dialog`**

2314

* **`org.gnome.gtk.ResponseType`**

2315

* **`org.gnome.gtk.MessageDialog`**

2316

* **`org.gnome.gtk.MessageType`**

2317

* **`org.gnome.gtk.ButtonsType`**

2318

* **`org.gnome.gtk.FileChooserDialog`**

2319

2320

And finally, minor improvements to all sorts of stuff:

2321

2322

* **`org.gnome.gtk.Container`**

2323

* **`org.gnome.gtk.Button`**

2324

* **`org.gnome.gtk.Box`**

2325

* **`org.gnome.gtk.Bin`**

2326

* **`org.gnome.gtk.Menu`**

2327

2328

notably from new contributor Mario Torre. Awesome!

2329

2330

For further details you can always grab a copy of the sources and run

2331

2332

$ bzr diff -r tag:v4.0.4..tag:v4.0.5

2333

2334

to see the complete code delta.

2335

2336

Screenshots

2337

-----------

2338

2339

<img src="doc/api/4.1/org/gnome/gtk/Window.png" alt="" style="float: right;

2340

text-align: right; padding-left: 15px;" /> For fun we built in a capability to

2341

create demonstrations to be captured as screenshots to illustrate various

2342

things. It doesn't get more basic than the example on the

2343

[`Window`][api-Window] documentation page, but it's a nice touch. `:)` We've

2344

screenshots for a number of Dialog classes and one for the TreeView page. I

2345

imagine we'll build up a nice library of images in the next few months (yes,

2346

dear contributors, you can add snapshots to the list of things we'll be

2347

expecting along with well written documentation and unit tests when submitting

2348

additions to the public API).

2349

2350

Building and requirements

2351

-------------------------

2352

2353

The library now depends on GTK >= 2.12. Those packaging java-gnome for their

2354

distributions please take note.

2355

2356

Looking ahead

2357

-------------

2358

2359

Continuing to expand the coverage levels in the classes already exposed will

2360

continue to dominate our attention; there's still a long way to go but we're

2361

pleased with the progress we've made so far; you can definitely build real

2362

applications with java-gnome now.

2363

2364

The next release also ought to include preliminary coverage of GConf and

2365

Cairo. Doing each justice will again take a serious amount of work, but will

2366

continue to grow the fun things you can do with java-gnome.

2367

2368

AfC

2369

2370

[example-treeview]: http://research.operationaldynamics.com/bzr/java-gnome/mainline/doc/examples/treeview/ExampleTrailHeads.java

2371

[api-window]: doc/api/4.1/org/gnome/gtk/Window.html

2372

2373

2374

2375

Arch packages

2376

=============

2377

2378

java-gnome now builds on [Arch Linux](http://www.archlinux.org/) and is

2379

packaged there. Thanks to Timm Preetz for having done the legwork for this!

2380

2381

AfC

2382

2383

2384

2385

Trees and Branches

2386

==================

2387

2388

Lots of ongoing work.

2389

2390

The major focus over the last three months has been on the '`treeview`' branch.

2391

Andrew Cowie, backed by Srichand Pendyala, has made awesome progress in working

2392

out the engineering necessary to support GTK's powerful but complex

2393

TreeView/TreeModel system and designing an appropriate public API by which

2394

java-gnome can present it. This has taken most of September and October but is

2395

working really well at this point. This branch should be ready for merging to

2396

'`mainline`' in the next week or two; just need to bring the documentation up

2397

to release quality and we're set.

2398

2399

Vreixo Formoso and Thomas Schmitz have done some great work to expose the

2400

Dialog family of classes. This work has exposed a few bugs in our internals,

2401

but thanks to some expert help from Owen Taylor we should have that sorted out

2402

soon. Work to fix that is taking place on the '`delete`' branch.

2403

2404

Andrew Cowie, helped by Behdad Esfahbod, has begun work on a binding of the

2405

Cairo library. This work is still experimental at this stage, but we'll merge

2406

this '`cairo`' branch in so we can to at least set the tone for what will be an

2407

exciting addition to java-gnome over the coming months.

2408

2409

Once we land these branches we should be able to polish things up for the

2410

release of 4.0.5, hopefully by the end of November.

2411

2412

AfC

2413

2414

2415

2416

java-gnome 4.0.4 (26 Sep 2007)

2417

==============================

2418

2419

_Coverage increasing!_

2420

2421

Most of our work continues to be on infrastructure and architecture, improving

2422

the code generator that outputs the translation Java layer and JNI C layer

2423

which allow bindings hackers to reach the underlying native libraries.

2424

Nevertheless, there have been a number of publicly visible improvements across

2425

the board, so we wanted to push out a release highlighting these contributions!

2426

2427

Documentation improvements

2428

--------------------------

2429

2430

Continuing our effort to have extensive developer friendly tutorial style

2431

documentation, there have been major additions to a number of existing classes.

2432

Of particular note is the Window class, containing the various utility methods

2433

used to ask the window manager to do things for you (we've also started

2434

exposing some of the deeper parts of the GTK toolkit, though only a few things

2435

that were immediately related to window management).

2436

2437

* **`org.gnome.gtk.Window`**

2438

* **`org.gnome.gtk.Widget`**

2439

* **`org.gnome.gdk.Screen`**

2440

* **`org.gnome.gdk.Window`**

2441

2442

While the topic of thread safety was discussed at considerable length in the

2443

last release, we have added some of the more relevant information to the code

2444

documentation to reinforce its importance.

2445

2446

* **`org.gnome.gdk.Gdk`**'s `lock`

2447

2448

New coverage

2449

------------

2450

2451

Numerous people have been hard at work developing new coverage. The standards

2452

for accepting patches which expose public API are high, so it's awesome to see

2453

bundles accepted for being merged to `mainline` from new contributors Thomas

2454

Schmitz, Wouter Bolsterlee, and Nat Pryce.

2455

2456

The infrastructure for a number of areas important to supporting applications

2457

including Menus, Toolbars, and Actions has been put in place:

2458

2459

* **`org.gnome.gtk.Toolbar`**

2460

* **`org.gnome.gtk.ToolItem`**

2461

* **`org.gnome.gtk.ToolButton`**

2462

* **`org.gnome.gtk.ToggleToolButton`**

2463

* **`org.gnome.gtk.MenuToolButton`**

2464

* **`org.gnome.gtk.SeparatorToolItem`**

2465

* **`org.gnome.gtk.MenuItem`**

2466

* **`org.gnome.gtk.CheckMenuItem`**

2467

* **`org.gnome.gtk.SeparatorMenuItem`**

2468

* **`org.gnome.gtk.Action`**

2469

* **`org.gnome.gtk.ActionGroup`**

2470

2471

A number of Container related Widgets have been added, though coverage is

2472

preliminary. There have, of course, also been a number of minor improvements in

2473

other existing classes, including:

2474

2475

* **`org.gnome.gtk.Notebook`**

2476

* **`org.gnome.gtk.ScrolledWindow`**

2477

* **`org.gnome.gtk.Misc`**

2478

* **`org.gnome.gtk.ButtonBox`**

2479

* **`org.gnome.gtk.HButtonBox`**

2480

* **`org.gnome.gtk.VButtonBox`**

2481

* **`org.gnome.gtk.Label`**

2482

2483

and even:

2484

2485

* **`org.gnome.gtk.StatusIcon`**

2486

2487

Along with these goes a variety of miscellaneous constants and wrappers around

2488

the stock item identifiers:

2489

2490

* **`org.gnome.gtk.Alignment`**

2491

* **`org.gnome.gtk.ImageType`**

2492

* **`org.gnome.gtk.ButtonBoxStyle`**

2493

* **`org.gnome.gtk.Justification`**

2494

* **`org.gnome.gtk.Orientation`**

2495

* **`org.gnome.gtk.Stock`**

2496

* **`org.gnome.gdk.Gravity`**

2497

2498

Internals

2499

---------

2500

2501

Vreixo Formoso carried out an important refactoring to the type database and

2502

Generator family of classes in the code generator, with the result that more of

2503

the array passing and out-parameter cases are now being handled correctly. This

2504

kind of work is usually thankless and taken for granted, but it's hugely

2505

appreciated!

2506

2507

The real gains are in internal quality. A number of serious bugs and

2508

limitations have been overcome (`Glade` is working again, for example). The

2509

generated code now guards against improper use (you can't pass a `null` pointer

2510

unless it's allowed by the underlying library). Related to this is handling of

2511

"`GError`" -- Java side, bindings hackers will get `GlibException` which they

2512

can then re-throw as an appropriate Java Exception, say `FileNotFoundException`

2513

in the case of not being able to open a file.

2514

2515

This all goes along with numerous build system fixes by Srichand Pendyala to

2516

make for an increasingly robust project. Thanks guys!

2517

2518

Looking ahead

2519

-------------

2520

2521

As mentioned above, we have mostly been focused on areas other than public API,

2522

but it is expanding steadily. The hard work on infrastructure, however, is

2523

starting to pay off, and the next release should include coverage of TreeView,

2524

GTK's powerful but complex list Widget.

2525

2526

AfC

2527

2528

2529

2530

Gentoo packages

2531

===============

2532

2533

The java-gnome bindings suite is now available in [Gentoo

2534

Linux](http://www.gentoo.org/). An `.ebuild` for 4.0.3 has been merged to

2535

Portage in

2536

2537

* `dev-java/java-gnome`

2538

2539

If you need help installing it, see the the Gentoo page in the

2540

[download](/get/gentoo.php) section here.

2541

2542

Thanks to the people who pushed this through: Xerces MC for having submitted an

2543

initial `.ebuild`, Petteri Räty (Gentoo dev and Java team lead) for having

2544

fixed it up, and Christoph Brill for testing.

2545

2546

AfC

2547

2548

2549

2550

java-gnome 4.0.3 (31 Jul 2007)

2551

==============================

2552

2553

_The code generator has landed!_

2554

2555

2556

Work has been underway for several months to develop the next stage of the new

2557

java-gnome: the code generator that will output the tedious translation and

2558

native layers that allow us to glue our public API to the native GNOME

2559

libraries. With this release we're pleased to announce that the code generator

2560

is a reality!

2561

2562

Generated translation and JNI layers

2563

------------------------------------

2564

2565

The primary goal of the java-gnome 4.0 re-engineering effort has been to switch

2566

to an architecture whereby we could _generate_ the bulk of the machinery

2567

necessary to take make native calls into the GNOME libraries from Java.

2568

2569

Extensive prototyping was done to establish the detailed design and to validate

2570

the architecture we had developed. Releases 4.0.0 through 4.0.2 contained this

2571

work along with mockups of the "translation" layer (the Java code that

2572

downshifts from our Proxy objects to primitives suitable to pass over the JNI

2573

boundary, along with the `native` declarations necessary in order to call

2574

methods actually written in C) and of the "JNI layer" (the C code that

2575

implements the methods declared in the translation layer which in turn coverts

2576

parameters into GLib terms and then makes the actual function call into the

2577

appropriate GNOME library).

2578

2579

With a solid foundation proving that our design was sound, we subsequently

2580

began the long effort to implement a code generator which would output these

2581

Java and C layers, allowing us to replace the `mockup/` directory and at last

2582

leave behind the shackles of entirely hand written bindings. Over the past five

2583

months, the java-gnome hackers have been steadily working on the 'codegen'

2584

branch. The nature of the challenge meant that we had to have most of the code

2585

in place before any of it would be useful -- never an enviable task to be

2586

working on. Thanks to the hard work of Andrew Cowie, Vreixo Formoso Lopes, and

2587

Srichand Pendyala, we reached the point where the output Java code compiled in

2588

May, and the output C code successfully compiled in by the end of June.

2589

Tremendous.

2590

2591

We've been bug hunting and refining since then, pushing towards the point where

2592

we could merge back to 'mainline', at last replacing the hand written mockup

2593

code. We are today pleased to announce the culmination of that work with the

2594

release of java-gnome 4.0.3.

2595

2596

_This post on the [development of the java-gnome code generator][codegen]

2597

contains further details should you be interested; the file

2598

[5a-Architecture.txt][architecture] in the `doc/design/` directory of the

2599

source code explains the rationale and origin of the engineering design._

2600

2601

New coverage

2602

------------

2603

2604

Although our focus has evidently been on getting the generator into working

2605

order, there have nevertheless been a few minor coverage additions along the

2606

way:

2607

2608

* **`org.gnome.gtk.Entry`**

2609

* **`org.gnome.gtk.Separator`**

2610

* **`org.gnome.gtk.HSeparator`**

2611

* **`org.gnome.gtk.VSeparator`**

2612

* **`org.gnome.gtk.Frame`**

2613

* **`org.gnome.gtk.Calendar`**

2614

* **`org.gnome.gtk.Notebook`**

2615

* **`org.gnome.gtk.Image`**

2616

* **`org.gnome.gtk.Menu`**

2617

* **`org.gnome.gtk.MenuBar`**

2618

* **`org.gnome.gtk.MenuItem`**

2619

* **`org.gnome.gtk.ToggleButton`**

2620

* **`org.gnome.gtk.CheckButton`**

2621

2622

which are largely to the credit of Sebastian Mancke for having submitted them

2623

and Srichand Pendyala for having fixed up their JavaDoc. There have also been

2624

steady improvements to a number of other classes; notably further signals and

2625

utility methods exposed in:

2626

2627

* **`org.gnome.gtk.Widget`**

2628

* **`org.gnome.gtk.Container`**

2629

2630

along with some preliminary coverage of the lower level GDK event machinery:

2631

2632

* **`org.gnome.gdk.Event`**

2633

* **`org.gnome.gdk.EventType`**

2634

2635

As is reasonable given our focus on writing the actual translation and JNI

2636

layer generators, most of these present only one or two methods from the

2637

underlying native class. Coverage will steadily improve as people contribute

2638

their knowledge and experience in documentation form.

2639

2640

_People upgrading from 4.0.2 will actually notice that there are stubs for

2641

**all** of the public API classes; this was necessary to make the generated

2642

code compile. Most of these are empty as yet._

2643

2644

GList and friends

2645

-----------------

2646

2647

`GList` and `GSList` are the native GLib data structures used to represent

2648

lists and are the return type from quite a few methods across GTK. Vreixo

2649

Formoso Lopes worked out how to handle and working our wrap/unwrap functions

2650

for us to use in the JNI layer made a significant contribution to reducing our

2651

blacklisted method count.

2652

2653

Flags

2654

-----

2655

2656

We've also worked out handling of native types that, while type defined as

2657

enums, are actually bit fields. These are used occasionally in GTK to express

2658

options; two examples now exposed are:

2659

2660

* **`org.gnome.gtk.CalendarDisplayOptions`**

2661

* **`org.gnome.gdk.WindowState`**

2662

2663

Flags subclasses present an `or()` function allowing you to combine individual

2664

Flags constants into a new composite Flags object. Yes it's a lot of machinery

2665

to do a logical `|`, but being strongly typed is a hallmark of java-gnome.

2666

2667

Build improvements

2668

------------------

2669

2670

No release would be complete without mentioning that the code builds on more

2671

systems than it did before! Thanks to Maciej Piechotka and Srichand Pendyala

2672

for fixing problems resulting from Debian and Ubuntu strangeness.

2673

2674

The build internally now uses an optimized script that takes into account that

2675

even though the code generator may have run the translation and jni files may

2676

not actually be different. This was causing problems as Make only looks at file

2677

modification time. Instead, `build/faster` (great name, huh?) will only rebuild

2678

a target when source contents have changed. This was necessary for bindings

2679

hackers working in Eclipse; every time a file was saved Eclipse would merrily

2680

spawn off an auto-build which sooner or later would block the IDE UI. Yuk.

2681

Addressing this has also resulted in a faster build for everyone; all good.

2682

2683

The internal build script _should_ be transparent; you still run `./configure`

2684

and `make` as before. If you experience problems let us know.

2685

2686

Thread safety

2687

-------------

2688

2689

In addition to the code generator, java-gnome 4.0.3 incorporates a

2690

comprehensive thread safety strategy.

2691

2692

None of the major Java graphical toolkits out there let you make GUI calls from

2693

threads other than the "main" one; they're all single threaded. Even if all you

2694

want to do is a quick worker thread to carry out some input validation in the

2695

background after the user presses "OK", you have to jump through horrific

2696

contortions to do so safely, resulting in cumbersome, clunky code.

2697

2698

By contrast, the new Java bindings of GTK presented in java-gnome are

2699

**transparently thread safe**, the first and only graphical user interface

2700

widget toolkit for Java to be so! We integrate properly with the underlying GDK

2701

thread lock and as a result you can safely make calls to various GTK methods

2702

from worker threads! This has been a long sought after goal and we hope a

2703

significant contribution to helping developers write elegant code.

2704

2705

Every call made to the native libraries is protected by entering the "GDK lock"

2706

[that's `gdk_threads_enter/leave()` for those familiar with the C side of

2707

things]. The lock used is actually a Java side `synchronized` monitor and

2708

therefore reentrant; nested calls all behave properly. When in a signal handler

2709

callback the GDK lock is already held (you're "in" the main loop when a

2710

callback happens), but since it just works transparently you don't need to

2711

worry about it. If you do find a need to take the lock into account explicitly

2712

in your own code, see `Gdk.lock` in `org.gnome.gdk`.

2713

2714

_It is worth noting that we have been warned that there are certain to be

2715

places in the underlying libraries that do not yet live up to the requirements

2716

of the GDK threads model -- thus we will likely end up tripping over such

2717

things as we slowly add API coverage. We regard such inevitable instances as an

2718

opportunity to help contribute to improving the stability of the underlying

2719

libraries and will actively work with their maintainers to identify and resolve

2720

such issues. Nevertheless, in testing thus far our multi-threaded use of GTK

2721

has been rock solid. See these posts on [GTK thread

2722

"awareness"][gtk-thread-awareness] and [java-gnome's thread

2723

strategy][java-gnome-thread] if you wish further details on our approach to the

2724

thread safety question._

2725

2726

Thanks in particular to Owen Taylor for having helped us navigate these waters!

2727

2728

Looking ahead

2729

-------------

2730

2731

Taken together, these innovations represent the culmination of an immense

2732

amount of work towards realizing java-gnome as a viable platform for GTK and

2733

GNOME development.

2734

2735

Obviously with the generated translation layer in place the opportunity at last

2736

exists to start dramatically improving our coverage level, and we welcome

2737

contributions to this end. Prospective hackers are cautioned, however, that

2738

simply wrapping generated methods is insufficient -- public API will only be

2739

added when it is clearly documented and meets the [approachability][objectives]

2740

criterion.

2741

2742

There are still areas where the code generator needs to be improved; we need to

2743

improve our handling for arrays, lists, and out-parameters -- there are

2744

numerous permutations with all sorts of ugly corner cases.

2745

2746

Now that Free Java with support for generics is becoming widely available,

2747

4.0.3 will be the last release holding the language level to Java 1.4; starting

2748

the next cycle 1.5 will be the minimum language requirement and we will be

2749

leveraging generics and other 1.5 features from here on.

2750

2751

Most importantly, the primary focus of the next few months will be developing a

2752

quality binding for the backbone of many applications: the `TreeView` Widget

2753

and the underlying `TreeModel` which powers it. The APIs in the native library

2754

is hideously complicated and has long been the source of confusion and pain for

2755

developers in C; it has long been a major goal amongst the java-gnome hackers

2756

to present a public API with as friendly and usable an interface as possible.

2757

It'll be a good challenge.

2758

2759

AfC

2760

2761

[architecture]: /doc/design/5a-Architecture.html

2762

[codegen]: http://research.operationaldynamics.com/blogs/andrew/software/java-gnome/code-generator-cometh.html

2763

[objectives]: /objectives.php

2764

[gtk-thread-awareness]: http://research.operationaldynamics.com/blogs/andrew/software/gnome-desktop/gtk-thread-awareness.html

2765

[java-gnome-thread]: http://research.operationaldynamics.com/blogs/andrew/software/java-gnome/thread-safety-for-java.html

2766

2767

2768

2769

2770

java-gnome 4.0.2 (12 Feb 2007)

2771

==============================

2772

2773

_The End of the Beginning!_

2774

2775

Major bugfixes and refactorings

2776

-------------------------------

2777

2778

Setting and getting properties on GObjects requires some tricky manoeuvring.

2779

We implemented the code to do this early on, and it looked like our general

2780

mechanism for getting Proxy instances for arbitrary pointers was working fine

2781

for properties. It turns out, however, that when you call `g_type_name()` on a

2782

GValue _containing_ a GObject, it returns the name of the type that was listed

2783

when the property specification was registered, rather than saying it is a

2784

GValue (as you might expect) or what the object actually is (that you might

2785

_also_ reasonably expect).

2786

2787

This led to all kinds of nastiness since the type name was what we were using

2788

in our `instanceFor()` mechanism to discriminate (on the Java side) what kind

2789

of Proxy subclass to create. The example we tripped over was asking for the

2790

parent property of a Button packed into a VBox. What `g_type_name()` told us

2791

was "GtkContainer", not "GtkVBox"! And that was a big problem, because

2792

Container is abstract, and besides, we want to instantiate a concrete VBox

2793

Proxy, not a Container one!

2794

2795

Solving the problem involved major changes to:

2796

2797

* **`org.gnome.glib.Value`**

2798

* **`org.gnome.glib.Object`**

2799

* `org.gnome.glib.Plumbing`

2800

* `org.gnome.glib.GValue`

2801

* `org.gnome.glib.GObject`

2802

2803

The solution basically boiled down to having two separate code paths: one

2804

named `objectFor()` [a greatly simplified version of the previous

2805

`instanceFor()`] which returns normal Proxy objects for GObject subclasses

2806

(Buttons and Labels and whatnot), and a new code path available via

2807

`valueFor()` to specifically return our GValue Proxy for the cases where we

2808

know we're getting a GValue back. Since that occurs in limited and known

2809

circumstances only (ie, when we're getting properties) it's no problem to know

2810

which to use when.

2811

2812

Thanks to Davyd Madeley for extensive debugging assistance, and credit to

2813

Manish Singh, James Henstridge, and Malcolm Tredinnick for having analyzed the

2814

root cause issue and having clarified that two code paths would indeed be

2815

necessary.

2816

2817

As often happens when you kick a stone loose, we were able to do a number of

2818

refactorings to clean things up. This eventually led to the realization (ok,

2819

epiphany) that our treatment of the GValue mechanism was needlessly complex.

2820

Toss. We no longer have individual Value subclasses for each different

2821

fundamental type, but rather just leave them as opaque references:

2822

2823

*

2824

`org.gnome.glib.Fundamental`

2825

*

2826

`org.gnome.glib.StringValue`

2827

*

2828

`org.gnome.glib.BooleanValue`

2829

*

2830

`org.gnome.glib.IntegerValue`

2831

*

2832

`org.gnome.glib.EnumValue`

2833

*

2834

`org.gnome.glib.ObjectValue`

2835

* **`org.gnome.glib.Value`**

2836

* `org.gnome.glib.Plumbing`

2837

2838

This allowed a further simplification of the `valueFor()` mechanism and even

2839

more smashing about in Plumbing with a chainsaw. Net result was a _reduction_

2840

by several hundred lines of code. Yeay!

2841

2842

All of these changes were confined to the internals of the binding machinery

2843

and are not user visible.

2844

2845

Loading `.glade` files

2846

----------------------

2847

2848

User interface designers are nothing new, but one of the really cool things

2849

about GTK has long been the existence of `libglade`. It's a library which

2850

takes the output of a one of the GNOME user interface designers (such as such

2851

as **Glade 3** or **Gazpacho**) and dynamically, at runtime, generates live

2852

Windows full of Widgets!

2853

2854

With the arbitrary Proxy retrieval sorted out, the beginnings of a binding of

2855

`libglade` was possible. None of the fancy stuff is there yet, but a `.glade`

2856

file can be loaded, and Widgets retrieved from the instantiated tree.

2857

2858

* **`org.gnome.glade.Glade`**

2859

* **`org.gnome.glade.Xml`**

2860

* _`org.gnome.glade.GladeXml`_

2861

2862

The JavaDoc for these classes clearly indicates that this is preliminary and

2863

subject to change. It may well all be blown away when GtkBuilder lands. We'll

2864

see.

2865

2866

Testing framework

2867

-----------------

2868

2869

We've introduced the beginnings of a unit test framework. At the moment, this

2870

just evaluates various getters and setters without doing anything that

2871

requires the main loop. Despite this, the unit tests end up exercising the

2872

entire Proxy system discussed above; validating that the properties set and

2873

get and that the correct Proxy object is returned through a round trip is no

2874

mean feat.

2875

2876

You can run the suite from Eclipse, by specifying a JUnit 3 launcher on class

2877

UnitTests in the default package in `tests/java`, or by running

2878

2879

$ make test

2880

2881

from the command line.

2882

2883

Further coverage

2884

----------------

2885

2886

This release also sees the addition of:

2887

2888

* **`org.gnome.gtk.FileChooser`**

2889

* **`org.gnome.gtk.FileChooserAction`**

2890

* **`org.gnome.gtk.FileChooserButton`**

2891

2892

Along with mocked up code for:

2893

2894

* _`org.gnome.gtk.GtkFileChooser`_

2895

* _`org.gnome.gtk.GtkFileChooserAction`_

2896

* _`org.gnome.gtk.GtkFileChooserButton`_

2897

2898

This is significant because GtkFileChooser is an _interface_ in GTK, and

2899

GtkFileChooserButton implements it. We'd been putting off the question of

2900

dealing with GInterface (would it work or be a major problem?) for a while

2901

now. We were delighted to find that the design implied by the re-engineered

2902

bindings handled it cleanly, elegantly, and without any fuss. Another nice

2903

validation of our new architecture.

2904

2905

Finally, a number of new signals were exposed on:

2906

2907

* **`org.gnome.gtk.Widget`**

2908

2909

though these were mostly the result of doing live demonstrations at

2910

conferences of how easy extending the coverage of the new bindings is.

2911

2912

Memory management

2913

-----------------

2914

2915

We have successfully implemented full GObject memory management in java-gnome

2916

4.0 using GLib's ToggleRef mechanism.

2917

2918

A strongly referenced Java Proxy will not allow its GObject to be destroyed

2919

out from underneath it; meanwhile, as long as the GObject is still referenced

2920

by something other than java-gnome, an otherwise only weakly reachable Java

2921

object that Proxies it will not be finalized. When the situation _does_ occur

2922

whereby the GObject is only referenced from java-gnome, and the Java object is

2923

no longer strongly referenced by any other Java objects, then the Java object

2924

can be garbage collected and the GObject will be unref()'d and destroyed.

2925

2926

You can watch the reference system in action if you set

2927

`Debug.MEMORY_MANAGEMENT` to `true`.

2928

2929

Huge thanks go to Vreixo Formoso Lopes who collaborated on the design,

2930

reviewed the implementation, and contributed test case code.

2931

2932

Build system improvements

2933

-------------------------

2934

2935

A better detection of jni.h is done on Ubuntu, thanks to Michael Kedzierski.

2936

This makes java-gnome more likely to build out of the box on Debian-derived

2937

systems.

2938

2939

On the eve of release, Srichand Pendyala noticed that if you are running such

2940

a system, a package named `libglade-dev` needs to be installed. Of course, on

2941

more modern systems all the necessary dependencies are present merely by

2942

having GNOME installed in the first place. We'll add a check for this Debian

2943

specific behaviour in 4.0.3.

2944

2945

The `VERSION` and `APIVERSION` constants were moved to

2946

2947

* `org.gnome.gtk.Version`

2948

2949

so that anyone working on the Gtk main class isn't forced to do a

2950

re-configuration every time they save.

2951

2952

Installation and Packaging

2953

--------------------------

2954

2955

java-gnome 4.0 now has the standard `make install` command, and the equally

2956

standard `--prefix` option to `./configure`.

2957

2958

$ ./configure --prefix=/usr

2959

$ make

2960

$ sudo make install

2961

2962

The `install` target understands the `DESTDIR` variable used by packagers to

2963

install to a specified prefix _within_ a temporary directory.

2964

2965

See the [`README`](README.html) file for details.

2966

2967

Looking ahead

2968

-------------

2969

2970

The feature additions described above were done to bring java-gnome up to

2971

speed for the GTK & GNOME tutorial given at [linux.conf.au][LCA]. With that

2972

past, we're not going to do any more manual mockups of code in what will be

2973

the generated layers. Focus now turns to designing and implementing the tool

2974

that will parse `.defs` files and output the translation code.

2975

2976

Once we secure funding for the project, the code generator will be our top

2977

priority and shouldn't take more than a couple months to complete.

2978

2979

AfC

2980

2981

[LCA]: http://lca2007.linux.org.au/talk/258

2982

2983

2984

2985

2986

java-gnome 4.0.1 (05 Jan 2007)

2987

==============================

2988

2989

_It's not really a prototype anymore! the design works, and so the code that

2990

is here is forming the foundation of the new Java bindings for GTK and GNOME._

2991

2992

While there are some significant pieces of engineering that are yet to be

2993

done, and of course a universe of coverage yet to write, we're pleased to mark

2994

the milestone of the prototype having proved itself to be stable and the

2995

strong foundation that we need. In this release:

2996

2997

Project documentation

2998

---------------------

2999

3000

Import project documentation, initially consisting of the re-engineering

3001

emails written by Andrew Cowie to the java-gnome-hackers mailing list, and

3002

expanded to include top level [`README`](README.html) and

3003

[`HACKING`](HACKING.html) files, and a style guide for contributors to follow.

3004

All documentation [re]formatted in Markdown syntax so as to be renderable to

3005

web pages. See [`doc/design/`](doc/design/START.html) and

3006

[`doc/style/`](doc/style/).

3007

3008

Project website

3009

---------------

3010

3011

Create an entirely new website for <http://java-gnome.sourceforge.net/>,

3012

introducing sections "[About](/about/)", "[Documentation](/doc/)",

3013

"[Download](/get/)" and "[Interact](/lists/)" to discuss the the

3014

project as a whole, to be a home for the documentation, to provide

3015

instructions on how to get java-gnome, and information about the mailing lists

3016

and IRC channel, respectively.

3017

3018

The website is no longer a wiki but is entirely within the source code of

3019

java-gnome itself. See the `web/public/` directory; improvements welcome.

3020

3021

Major engineering

3022

-----------------

3023

3024

Quite significantly, the infrastructure to get a Proxy or Constant instance

3025

for any arbitrary C side pointer or enum is complete, involving _significant_

3026

work to:

3027

3028

* `org.freedestkop.bindings.Plumbing`

3029

* **`org.freedestkop.bindings.Proxy`**

3030

* **`org.freedestkop.bindings.Constant`**

3031

* `org.gnome.glib.Plumbing`

3032

* **`org.gnome.glib.Value`**

3033

* `org.gnome.glib.GValue`

3034

* `org.gnome.glib.Fundamental`

3035

* **`org.gnome.glib.Object`**

3036

3037

Along with the corresponding C side code, especially in `GValue.c`

3038

3039

This was a necessary building block in order to complete the generalized

3040

`getProperty()` mechanism that, while hidden from public view, is nevertheless

3041

a major aspect of the GObject tool chest and is usable by bindings hackers

3042

when necessary. The generalized instance mechanism was the last major

3043

engineering hurdle that needed to be achieved in order to prove the new

3044

bindings design.

3045

3046

New coverage

3047

------------

3048

3049

* **`org.gnome.gtk.Label`**

3050

* **`org.gnome.gtk.Fixed`**

3051

* **`org.gnome.gtk.Box`**

3052

* **`org.gnome.gtk.VBox`**

3053

* **`org.gnome.gtk.HBox`**

3054

3055

Along with

3056

3057

* _`org.gnome.gtk.GtkLabel`_

3058

* _`org.gnome.gtk.GtkFixed`_

3059

* _`org.gnome.gtk.GtkBox`_

3060

* _`org.gnome.gtk.GtkVBox`_

3061

* _`org.gnome.gtk.GtkHBox`_

3062

3063

And corresponding [working] mockup native code.

3064

3065

Compliments to Srichand Pendyala from Bangalore, India for being the first

3066

external hacker to have a patch accepted to mainline! He contributed methods

3067

to Label and initiated the implementation of the Fixed class. In so doing, he

3068

also helped work the bugs out of the `bzr bundle` submission process. Awesome.

3069

3070

Build improvements

3071

------------------

3072

3073

java-gnome now builds on Ubuntu and OpenSolaris in addition to its home turf

3074

of Gentoo. Thanks to John Rice of Sun Microsystems who provided the guidance

3075

allowing us to port Equivalence to Solaris some months ago, and Laszlo Peter,

3076

also of Sun Ireland, for several fixes to allow configure to recognize a wider

3077

range of Solaris environments.

3078

3079

The tiny example program that we have been using to validate the code,

3080

`Experiment` is now compiled by the build system if you so request. Try `make

3081

demo`.

3082

3083

API documentation

3084

-----------------

3085

3086

Extensive attention has been paid to the JavaDoc for the few methods that are

3087

presented so as to clearly set the standard required. The canonical JavaDoc

3088

for the project is available at the website with a stable URL and can be

3089

linked to.

3090

3091

All source code [comments, ie JavaDoc] have been spell checked! Initial top

3092

level `overview.html` and `package.html` files have also been written to help

3093

round out the JavaDoc.

3094

3095

AfC

3096

3097

3098

3099

3100

java-gnome 4.0.0 (26 Nov 2006)

3101

==============================

3102

3103

_Initial release of the java-gnome 4.0 prototype, corresponding to the first

3104

public demonstration of the new bindings done at

3105

[foss.in/2006](http://foss.in/2006/) at Bangalore, India._

3106

3107

The prototype is fully functional and is intended to prove the design and

3108

architecture we have arrived at as a result of the re-engineering process. It

3109

includes both real wrapper layer classes that are the seed from which our

3110

public API will grow, along with the infrastructure that the wrapper layer

3111

depends on.

3112

3113

Initial coverage

3114

----------------

3115

3116

Wrapper layer presenting the public API to developers (publicly visible

3117

classes in bold):

3118

3119

* **`org.freedesktop.bindings.Proxy`**

3120

* **`org.gnome.glib.Value`**

3121

* **`org.gnome.glib.Object`**

3122

* **`org.gnome.gtk.Object`**

3123

* **`org.gnome.gtk.Widget`**

3124

* **`org.gnome.gtk.Container`**

3125

* **`org.gnome.gtk.Bin`**

3126

* **`org.gnome.gtk.Button`**

3127

* **`org.gnome.gtk.Window`**

3128

3129

Along with complete translation layer implementations for each:

3130

3131

* `org.freedesktop.bindings.Plumbing`

3132

* `org.gnome.glib.Plumbing`

3133

* `org.gnome.glib.GValue`

3134

* `org.gnome.glib.GObject`

3135

* `org.gnome.gtk.GtkObject`

3136

* _`org.gnome.gtk.GtkWidget`_

3137

* _`org.gnome.gtk.GtkContainer`_

3138

* _`org.gnome.gtk.GtkBin`_

3139

* _`org.gnome.gtk.GtkButton`_

3140

* _`org.gnome.gtk.GtkWindow`_

3141

3142

At present the bindings mock up the code that will be generated with

3143

temporarily hand written substitutes (ie, those in italics above) for both

3144

translation (Java) and native (C) layers. These will do until we receive the

3145

funding to make the code generator a reality; we certainly don't want to be

3146

writing much more translation layer Java and C code by hand. Yuk.

3147

3148

3149

Signal API

3150

----------

3151

3152

The defining aspect of GUI programming is, of course, that it is event driven.

3153

In addition to the "forward" direction of making calls to the native library

3154

and having return values bubble back up, there is the "reverse" direction of

3155

connecting callback handlers to the various signals that different Widgets

3156

offer, and having those signal events result in those handlers being invoked.

3157

3158

java-gnome 4.0 has an entirely new and redesigned signal connection and

3159

callback API. This functionality was demonstrated, and coverage of

3160

**`Button.CLICKED`** and **`Window.DELETE`** is now present and functional!

3161

The APIs used by GNOME language bindings to achieve this are some of the most

3162

voodoo I have ever seen. But it's hooked up, and it works. It's like black

3163

magic :)

3164

3165

Build

3166

-----

3167

3168

java-gnome is configured and built using Andrew Cowie's Equivalence build

3169

scripts. It builds on Gentoo and should build on a Debian or Fedora derived

3170

system as well. See [`README`](README.html) for further details.

3171

3172

At the moment, java-gnome is a single source package.

3173

3174

The source code is available via `bzr`. Again, see `README`.

3175

3176

AfC

3177

3178

<!--

3179

3180

3181

3182

As project documentation, this file forms an integral part of the source

3183

code of the library it accompanies, and thus is made available to you by its

3184

authors as open source software: you can redistribute it and/or modify it

3185

under the terms of the GNU General Public License version 2 ("GPL") as

3186

published by the Free Software Foundation.

3187

3188

This program is distributed in the hope that it will be useful, but WITHOUT

3189

ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

3190

FITNESS FOR A PARTICULAR PURPOSE. See the GPL for more details.

3191

3192

You should have received a copy of the GPL along with this program. If not,

3193

see http://www.gnu.org/licenses/. The authors of this program may be

3194

contacted through http://java-gnome.sourceforge.net/.

3195

3196

vim: set textwidth=78:

3197

3198

-->