Menu
▾
▴
[CIShell-SVN] SF.net SVN: cishell:[1235] trunk/core/org.cishell.utility.swt/src/org/ cishell/utility/swt
|
From: <pat...@us...> - 2011-03-07 11:33:23
|
Revision: 1235
http://cishell.svn.sourceforge.net/cishell/?rev=1235&view=rev
Author: pataphil
Date: 2011-03-07 11:33:16 +0000 (Mon, 07 Mar 2011)
Log Message:
-----------
* Documentation.
Modified Paths:
--------------
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ExpandableComponentWidget.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/FileSaveAs.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GUIBuilderUtilities.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GridContainer.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/SWTUtilities.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ScrolledComponentFactory.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLClickedListener.java
trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLMouseCursorListener.java
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ExpandableComponentWidget.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ExpandableComponentWidget.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ExpandableComponentWidget.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -13,8 +13,28 @@
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
-/**
- * This is meant to be subclassed.
+/** See ScrolledComponentFactory for more information on the overall picture of the layer that this
+ * class is part of.
+ * A LITTLE BIT OF HISTORY:
+ ** When tasked with writing the Static Executable Wizard, I ran into a lot of difficulty with
+ ** gracefully handling the dynamic addition and deletion of child components to scrolling
+ ** components. (By scrolling components, I mean the components that actually do the scrolling; that
+ ** is, they SCROLL their child components.) The problem relates to how SWT grid layouts want to be
+ ** sized--I believe that SWT is largely implemented to only handle GUIs that've been setup by time
+ ** the user interacts with them.
+ ** In order to try to make this process more graceful, I came up with this and its
+ ** related classes.
+ * HOW TO USE IT:
+ ** This class only makes sense if T corresponds to a GUI component in some fashion (though it
+ ** doesn't literally have to be an SWT component).
+ ** Override getColumnCount() to specify the number of columns each row has.
+ ** Override createHeaderArea() and createFooterArea() to specify if there should be a header and
+ ** footer, respectively, that is OUTSIDE of the scrolling area.
+ ** Override createColumnLabelTexts() to specify the column labels. The default implementation of
+ ** this method uses the column index to generate labels.
+ ** It's recommended against overriding addComponent() and removeComponent().
+ ** This class should be subclassed so specific column labels and any desired header/footer
+ ** can be generated.
*/
public class ExpandableComponentWidget<T> extends Composite {
public static final int COLUMN_AREA_LAYOUT_VERTICAL_SPACING = 1;
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/FileSaveAs.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/FileSaveAs.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/FileSaveAs.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -7,6 +7,7 @@
import org.eclipse.swt.widgets.FileDialog;
import org.eclipse.swt.widgets.Shell;
+// TODO: Find other places in the code base that do the same thing as this.
public class FileSaveAs {
public static final String DEFAULT_WINDOW_TITLE = "Save As";
public static final String CONFIRMATION_DIALOG_FORMAT =
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GUIBuilderUtilities.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GUIBuilderUtilities.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GUIBuilderUtilities.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -11,6 +11,10 @@
import org.eclipse.swt.widgets.Listener;
import org.eclipse.swt.widgets.Shell;
+/** These utilities are meant to handle a lot of common SWT operations that have little or no
+ * variation, such as the event dispatch loop (swtLoop()).
+ * Given the complex nature of UI programming, I'd consider this class to be deprecated.
+ */
public class GUIBuilderUtilities {
public static Display createDisplay() {
return new Display();
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GridContainer.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GridContainer.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/GridContainer.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -7,6 +7,12 @@
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Widget;
+/** SWT composite components with grid layouts don't have a way of accessing a child component at
+ * a given cell (x, y).
+ * GridContainer is designed to remedy this problem in a general sense. However, in order for it to
+ * be able to reliably do so, all child components should be added to the parent composite via
+ * (objects of) this class.
+ */
public class GridContainer {
private Composite actualParent;
private int columnCount;
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/SWTUtilities.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/SWTUtilities.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/SWTUtilities.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -10,6 +10,9 @@
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Display;
+/** TODO: The URL (http://-prefixed) parsing utilities in this class need to be updated to handle
+ * https as well.
+ */
public class SWTUtilities {
public static final Color DEFAULT_BACKGROUND_COLOR =
new Color(Display.getDefault(), 255, 255, 255);
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ScrolledComponentFactory.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ScrolledComponentFactory.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/ScrolledComponentFactory.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -2,7 +2,32 @@
import java.util.Map;
+/**
+ * Used with ExpandableComponentWidget<T> as part of a SWT-based layer for managing scrolling
+ * components, whose contents are dynamic (as in, rows can be added and removed dynamically).
+ * The original inspiration for this layer is that SWT doesn't play very nicely with this type of
+ * dynamic scrolling component (i.e. the ones where content is changed real-time).
+ * The scrolling components involved can be thought of as having rows of content, where all rows
+ * have the same number of elements. (So, think of a grid--hence GridContainer.)
+ */
public interface ScrolledComponentFactory<T> {
+ /** Construct a child widget of type T to be added to componentWidget.
+ * NOTE: The term "widget" in the name "constructWidget" refers to whatever T happens to be,
+ * which is not necessarily a widget (but may wrap one or more actual widgets).
+ * Parameters:
+ * componentWidget -- the parent component of the T (or its wrapped components)
+ * that we're creating.
+ * scrolledAreaGrid -- tracks the actual SWT components so individual rows of them can easily
+ * be removed in one operation.
+ * style -- any SWT style flags that should be used when creating child components. Somewhat
+ * deprecated; perhaps should be removed.
+ * arguments -- if any implementation ever had custom arguments, this would be the channel
+ * to use.
+ * index -- the index of the constructed T within componentWidget, such that calling
+ * componentWidget.removeComponent(index) will remove this constructed T object.
+ * uniqueIndex -- has no functional purpose in this layer, but can be used for things like
+ * unique name creation. (NOTE: It may have functional purposes in users of this layer.)
+ */
public T constructWidget(
ExpandableComponentWidget<T> componentWidget,
GridContainer scrolledAreaGrid,
@@ -11,5 +36,12 @@
int index,
int uniqueIndex) throws WidgetConstructionException;
+ /*
+ * Whenever a T is added or removed, the set of T may need to be reindexed so future add/remove
+ * operations behave properly.
+ * Parameters:
+ * component -- the component to reindex.
+ * newIndex -- the new index to give to component.
+ */
public void reindexComponent(T component, int newIndex);
}
\ No newline at end of file
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLClickedListener.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLClickedListener.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLClickedListener.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -9,8 +9,7 @@
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.program.Program;
-/*
- * Listens for clicks on urls and launches a browser.
+/** Listens for clicks on urls and launches a browser.
*/
public class URLClickedListener extends MouseAdapter {
private Map<Integer, String> offsetsToURLs = new HashMap<Integer, String>();
Modified: trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLMouseCursorListener.java
===================================================================
--- trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLMouseCursorListener.java 2011-03-04 16:27:45 UTC (rev 1234)
+++ trunk/core/org.cishell.utility.swt/src/org/cishell/utility/swt/URLMouseCursorListener.java 2011-03-07 11:33:16 UTC (rev 1235)
@@ -11,8 +11,7 @@
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.widgets.Composite;
-/*
- * Monitors the mouse and changes the cursor when it is over a URL.
+/** Monitors the mouse and changes the cursor when it is over a URL.
*/
public class URLMouseCursorListener implements MouseMoveListener {
private Map<Integer, String> offsetsToURLs = new HashMap<Integer, String>();
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
