Skip to content

Commit

Permalink
Refs #3 - added GUI section.
Browse files Browse the repository at this point in the history
  • Loading branch information
@cbmarcum
cbmarcum committed Jul 5, 2020
1 parent 8fe424f commit c33c647
Show file tree
Hide file tree
Showing 6 changed files with 212 additions and 10 deletions.
Binary file added docs/images/infobox.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/swingbuilder-1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/swingbuilder-2.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/warningbox.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
91 changes: 87 additions & 4 deletions docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ XIndexAccess xIndexSheets = UnoRuntime.queryInterface(XIndexAccess.class, xSheet
----

=== Static and Dynamic Types
While Groovy works great as a dynamic language where we can declare variables with the _def_ keyword, I prefer to declare
While Groovy works great as a dynamic language where we can declare variables with the `def` keyword, I prefer to declare
types most of the time. This is only my preference and not a requirement.

=== Property Access
Expand Down Expand Up @@ -126,7 +126,8 @@ If you start OpenOffice from the command line you can see stdout and stderr mess
The best way to explain the differences between the Java UNO API's and using Groovy with and without the extension is with some example code. Many of the examples are spreadsheet examples are from SCalc.java that is included with the AOO SDK.

=== Import Statement
To use the UnoExtension you need to add to your imports section
To use the UnoExtension you need to add to your imports section.

.Add the UnoExtension to imports
[source, groovy]
----
Expand Down Expand Up @@ -245,7 +246,7 @@ This first example will ignore that we already have a method to get a sheet by i

Example: Set the active sheet.

.With Extension (begin with an XSpreadsheetDocument `xSpreadsheetDocument` reference)
.With Extension (begin with an XSpreadsheetDocument xSpreadsheetDocument reference)
----
XSpreadsheets xSheets = xSpreadsheetDocument.sheets
XIndexAccess xIndexAccess = xSheets.guno(XIndexAccess.class)
Expand Down Expand Up @@ -352,7 +353,7 @@ xCell.vertJustify = com.sun.star.table.CellVertJustify.TOP
----

=== Cell Ranges
The GUNO Extension adds a method to XSpeadsheet to get the the cell ranges that match certain types.: +
The GUNO Extension adds a method to XSpreadsheet to get the the cell ranges that match certain types.: +
`XSheetCellRanges getCellRanges(Object type)` where type is one or a combination of http://www.openoffice.org/api/docs/common/ref/com/sun/star/sheet/CellFlags.html[CellFlag constants] added together.

.Without Extension
Expand Down Expand Up @@ -442,3 +443,85 @@ cellList.each() { cell ->
}
----

== Graphical User Interfaces
=== Message Box
UNO provides a XMessageBox to display UI messages to the user. There a a number of steps to get from an XComponentContext to displaying a message.

There are standard https://www.openoffice.org/api/docs/common/ref/com/sun/star/awt/MessageBoxType.html[MessageBoxType enums] used depending on the icon and https://www.openoffice.org/api/docs/common/ref/com/sun/star/awt/MessageBoxButtons.html[MessageBoxButton constants] for button combinations displayed. the INFOBOX type is different in that it will ignore the button parameter and use BUTTONS_OK and display a single OK button.

.Without Extension (begins with an XcomponentContext xContext reference)
[source,groovy]
----
XMultiComponentFactory xMCF = xContext.getServiceManager()
XDesktop xDesktop = xMCF.createInstanceWithContext("com.sun.star.frame.Desktop", xContext)
XFrame xFrame = xDesktop.getCurrentFrame()
Object oToolkit = xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", xContext)
XMessageBoxFactory xMessageBoxFactory = UnoRuntime.queryInterface(XMessageBoxFactory.class, oToolkit)
XWindow xWindow = xFrame.getContainerWindow()
XWindowPeer xWindowPeer = UnoRuntime.queryInterface(XWindowPeer.class, xWindow)
XMessageBox xMessageBox = xMessageBoxFactory.createMessageBox(xWindowPeer,
MessageBoxType.INFOBOX, MessageBoxButtons.BUTTONS_OK,
"Window Title", "This in an informative mesage...")
short infoBoxResult = xMessageBox.execute()
----

The GUNO extension adds two methods to XComponentContext that return a XMessageBox: +
`XMessageBox getMessageBox(MessageBoxType type, Integer buttons, String message)` that uses a default window title of "soffice" and +
`XMessageBox getMessageBox(MessageBoxType type, Integer buttons, String message, String title)` that includes a title parameter.

.With Extension (Info Box example using default title)
[source,groovy]
----
XMessageBox infoBox = xContext.getMessageBox(MessageBoxType.INFOBOX,
MessageBoxButtons.BUTTONS_OK, "This in an informative mesage...")
short infoBoxResult = infoBox.execute()
----
.Info Box
image::images/infobox.png[]

.With Extension (Warning Box example with title and default okay button and a cancel button)
[source,groovy]
----
String warnMsg = "This is a warning mesage...\nYou should be careful."
Integer warnButtons = MessageBoxButtons.BUTTONS_OK_CANCEL + MessageBoxButtons.DEFAULT_BUTTON_OK
XMessageBox warningBox = xContext.getMessageBox(MessageBoxType.WARNINGBOX,
warnButtons, warnMsg, "Warning Title")
short warnBoxResult = warningBox.execute()
----
.Warning Box
image::images/warningbox.png[]

=== Groovy SwingBuilder
If you're a Java developer you've probaly heard of Swing with was Java's 2nd generation UI Toolkit. Many developers have ran into threading issues leading to blocked and unresponsive UI's if Swing wasn't used correctly.

Groovy includes many examples of what they call Builders which are examples of a Domain Specific Language (DSL) focused on hierarchal structures. Builders are great for declaring content like HTML, XML, and in this case Swing. An added bonus is it takes care of handling the threading for you.

This simple example comes straight from the http://groovy-lang.org/swing.html[Groovy Swing] page. I modified the size dimension of the frame and added the return Integer at the end. Otherwise it runs as a AOO marco.

.Simple SwingBuilder Example
[source,groovy]
----
import groovy.swing.SwingBuilder
import java.awt.BorderLayout as BL
count = 0
new SwingBuilder().edt {
frame(title: 'Frame', size: [150, 80], show: true) {
borderLayout()
textlabel = label(text: 'Click the button!', constraints: BL.NORTH)
button(text:'Click Me',
actionPerformed: {count++; textlabel.text = "Clicked ${count} time(s)."; println "clicked"}, constraints:BL.SOUTH)
}
}
// Groovy OpenOffice scripts should always return 0
return 0
----
.After launch
image::images/swingbuilder-1.png[]
.After first button click
image::images/swingbuilder-2.png[]
131 changes: 125 additions & 6 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,12 @@ <h1>GUNO Extension Documentation</h1>
<li><a href="#truerangecontainer">RangeContainer</a></li>
</ul>
</li>
<li><a href="#truegraphical-user-interfaces">Graphical User Interfaces</a>
<ul class="sectlevel2">
<li><a href="#truemessage-box">Message Box</a></li>
<li><a href="#truegroovy-swingbuilder">Groovy SwingBuilder</a></li>
</ul>
</li>
</ul>
</div>
</div>
Expand Down Expand Up @@ -607,7 +613,7 @@ <h3 id="truecasting"><a class="anchor" href="#truecasting"></a>Casting</h3>
<div class="sect2">
<h3 id="truestatic-and-dynamic-types"><a class="anchor" href="#truestatic-and-dynamic-types"></a>Static and Dynamic Types</h3>
<div class="paragraph">
<p>While Groovy works great as a dynamic language where we can declare variables with the <em>def</em> keyword, I prefer to declare
<p>While Groovy works great as a dynamic language where we can declare variables with the <code>def</code> keyword, I prefer to declare
types most of the time. This is only my preference and not a requirement.</p>
</div>
</div>
Expand Down Expand Up @@ -679,10 +685,10 @@ <h2 id="trueusing-the-extension"><a class="anchor" href="#trueusing-the-extensio
<div class="sect2">
<h3 id="trueimport-statement"><a class="anchor" href="#trueimport-statement"></a>Import Statement</h3>
<div class="paragraph">
<p>To use the UnoExtension you need to add to your imports section
.Add the UnoExtension to imports</p>
<p>To use the UnoExtension you need to add to your imports section.</p>
</div>
<div class="listingblock">
<div class="title">Add the UnoExtension to imports</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">import org.openoffice.guno.UnoExtension</code></pre>
</div>
Expand Down Expand Up @@ -826,7 +832,7 @@ <h3 id="trueindex-access"><a class="anchor" href="#trueindex-access"></a>Index A
<p>Example: Set the active sheet.</p>
</div>
<div class="listingblock">
<div class="title">With Extension (begin with an XSpreadsheetDocument <code>xSpreadsheetDocument</code> reference)</div>
<div class="title">With Extension (begin with an XSpreadsheetDocument xSpreadsheetDocument reference)</div>
<div class="content">
<pre>XSpreadsheets xSheets = xSpreadsheetDocument.sheets
XIndexAccess xIndexAccess = xSheets.guno(XIndexAccess.class)
Expand Down Expand Up @@ -951,7 +957,7 @@ <h3 id="truecellvertjustify-enum"><a class="anchor" href="#truecellvertjustify-e
<div class="sect2">
<h3 id="truecell-ranges"><a class="anchor" href="#truecell-ranges"></a>Cell Ranges</h3>
<div class="paragraph">
<p>The GUNO Extension adds a method to XSpeadsheet to get the the cell ranges that match certain types.:<br>
<p>The GUNO Extension adds a method to XSpreadsheet to get the the cell ranges that match certain types.:<br>
<code>XSheetCellRanges getCellRanges(Object type)</code> where type is one or a combination of <a href="http://www.openoffice.org/api/docs/common/ref/com/sun/star/sheet/CellFlags.html">CellFlag constants</a> added together.</p>
</div>
<div class="listingblock">
Expand Down Expand Up @@ -1054,10 +1060,123 @@ <h3 id="truerangecontainer"><a class="anchor" href="#truerangecontainer"></a>Ran
</div>
</div>
</div>
<div class="sect1">
<h2 id="truegraphical-user-interfaces"><a class="anchor" href="#truegraphical-user-interfaces"></a>Graphical User Interfaces</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="truemessage-box"><a class="anchor" href="#truemessage-box"></a>Message Box</h3>
<div class="paragraph">
<p>UNO provides a XMessageBox to display UI messages to the user. There a a number of steps to get from an XComponentContext to displaying a message.</p>
</div>
<div class="paragraph">
<p>There are standard <a href="https://www.openoffice.org/api/docs/common/ref/com/sun/star/awt/MessageBoxType.html">MessageBoxType enums</a> used depending on the icon and <a href="https://www.openoffice.org/api/docs/common/ref/com/sun/star/awt/MessageBoxButtons.html">MessageBoxButton constants</a> for button combinations displayed. the INFOBOX type is different in that it will ignore the button parameter and use BUTTONS_OK and display a single OK button.</p>
</div>
<div class="listingblock">
<div class="title">Without Extension (begins with an XcomponentContext xContext reference)</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">XMultiComponentFactory xMCF = xContext.getServiceManager()
XDesktop xDesktop = xMCF.createInstanceWithContext("com.sun.star.frame.Desktop", xContext)
XFrame xFrame = xDesktop.getCurrentFrame()
Object oToolkit = xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", xContext)
XMessageBoxFactory xMessageBoxFactory = UnoRuntime.queryInterface(XMessageBoxFactory.class, oToolkit)
XWindow xWindow = xFrame.getContainerWindow()
XWindowPeer xWindowPeer = UnoRuntime.queryInterface(XWindowPeer.class, xWindow)

XMessageBox xMessageBox = xMessageBoxFactory.createMessageBox(xWindowPeer,
MessageBoxType.INFOBOX, MessageBoxButtons.BUTTONS_OK,
"Window Title", "This in an informative mesage...")

short infoBoxResult = xMessageBox.execute()</code></pre>
</div>
</div>
<div class="paragraph">
<p>The GUNO extension adds two methods to XComponentContext that return a XMessageBox:<br>
<code>XMessageBox getMessageBox(MessageBoxType type, Integer buttons, String message)</code> that uses a default window title of "soffice" and<br>
<code>XMessageBox getMessageBox(MessageBoxType type, Integer buttons, String message, String title)</code> that includes a title parameter.</p>
</div>
<div class="listingblock">
<div class="title">With Extension (Info Box example using default title)</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">XMessageBox infoBox = xContext.getMessageBox(MessageBoxType.INFOBOX,
MessageBoxButtons.BUTTONS_OK, "This in an informative mesage...")

short infoBoxResult = infoBox.execute()</code></pre>
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="images/infobox.png" alt="infobox">
</div>
<div class="title">Figure 1. Info Box</div>
</div>
<div class="listingblock">
<div class="title">With Extension (Warning Box example with title and default okay button and a cancel button)</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">String warnMsg = "This is a warning mesage...\nYou should be careful."
Integer warnButtons = MessageBoxButtons.BUTTONS_OK_CANCEL + MessageBoxButtons.DEFAULT_BUTTON_OK
XMessageBox warningBox = xContext.getMessageBox(MessageBoxType.WARNINGBOX,
warnButtons, warnMsg, "Warning Title")

short warnBoxResult = warningBox.execute()</code></pre>
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="images/warningbox.png" alt="warningbox">
</div>
<div class="title">Figure 2. Warning Box</div>
</div>
</div>
<div class="sect2">
<h3 id="truegroovy-swingbuilder"><a class="anchor" href="#truegroovy-swingbuilder"></a>Groovy SwingBuilder</h3>
<div class="paragraph">
<p>If you&#8217;re a Java developer you&#8217;ve probaly heard of Swing with was Java&#8217;s 2nd generation UI Toolkit. Many developers have ran into threading issues leading to blocked and unresponsive UI&#8217;s if Swing wasn&#8217;t used correctly.</p>
</div>
<div class="paragraph">
<p>Groovy includes many examples of what they call Builders which are examples of a Domain Specific Language (DSL) focused on hierarchal structures. Builders are great for declaring content like HTML, XML, and in this case Swing. An added bonus is it takes care of handling the threading for you.</p>
</div>
<div class="paragraph">
<p>This simple example comes straight from the <a href="http://groovy-lang.org/swing.html">Groovy Swing</a> page. I modified the size dimension of the frame and added the return Integer at the end. Otherwise it runs as a AOO marco.</p>
</div>
<div class="listingblock">
<div class="title">Simple SwingBuilder Example</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="groovy" class="language-groovy hljs">import groovy.swing.SwingBuilder
import java.awt.BorderLayout as BL

count = 0
new SwingBuilder().edt {
frame(title: 'Frame', size: [150, 80], show: true) {
borderLayout()
textlabel = label(text: 'Click the button!', constraints: BL.NORTH)
button(text:'Click Me',
actionPerformed: {count++; textlabel.text = "Clicked ${count} time(s)."; println "clicked"}, constraints:BL.SOUTH)
}
}

// Groovy OpenOffice scripts should always return 0
return 0</code></pre>
</div>
</div>
<div class="imageblock">
<div class="content">
<img src="images/swingbuilder-1.png" alt="swingbuilder 1">
</div>
<div class="title">Figure 3. After launch</div>
</div>
<div class="imageblock">
<div class="content">
<img src="images/swingbuilder-2.png" alt="swingbuilder 2">
</div>
<div class="title">Figure 4. After first button click</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2020-07-04 15:36:34 -0400
Last updated 2020-07-05 12:04:06 -0400
</div>
</div>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.6/styles/github.min.css">
Expand Down

0 comments on commit c33c647

Please sign in to comment.