You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by el...@apache.org on 2015/07/01 10:45:50 UTC
svn commit: r1688596 - in
/directory/site/trunk/content/studio/developers-howtos: ./
developers-howtos.mdtext howtos/ howtos/table-widget.mdtext
Author: elecharny
Date: Wed Jul 1 08:45:49 2015
New Revision: 1688596
URL: http://svn.apache.org/r1688596
Log:
Added some doco about the TableWidget class and usage
Added:
directory/site/trunk/content/studio/developers-howtos/
directory/site/trunk/content/studio/developers-howtos/developers-howtos.mdtext
directory/site/trunk/content/studio/developers-howtos/howtos/
directory/site/trunk/content/studio/developers-howtos/howtos/table-widget.mdtext
Added: directory/site/trunk/content/studio/developers-howtos/developers-howtos.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/studio/developers-howtos/developers-howtos.mdtext?rev=1688596&view=auto
==============================================================================
--- directory/site/trunk/content/studio/developers-howtos/developers-howtos.mdtext (added)
+++ directory/site/trunk/content/studio/developers-howtos/developers-howtos.mdtext Wed Jul 1 08:45:49 2015
@@ -0,0 +1,47 @@
+Title: Developers' Howtos
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Studio Developers' Howtos
+
+Theses guides give some insight about how is developped Studio, so that some new comers can jump in at a limited cost (well, sort of...)
+
+
+## Introduction
+
+Studio is an Eclipse&tm; RCP application, which can also be loaded into an Eclipse&tm; instance. It's a set of plugins :
+
+* a LDAP Browser
+* a LDAP Schema Editor
+* an embedded ApacheDS 2.0 server
+* an LDIF editor
+* an ApacheDS 2.0 configuration editor
+* an OpenDLAP&tm; 2.4 configuration editor
+
+and various utility plugins.
+
+## Prerequisites
+
+You can check about what is needed to be able to start coding on [the Developers' guide](../devezlopers-guide.mdtext).
+
+In any case, you need a Java JDK 7, Eclipse Luna-SR2, Maven 3.2.5, subversion 1.8.8.
+
+## Howtos
+
+ * [1 - Using the TableWidget<E> widget](howtos/table-widget.html)
+
+
Added: directory/site/trunk/content/studio/developers-howtos/howtos/table-widget.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/studio/developers-howtos/howtos/table-widget.mdtext?rev=1688596&view=auto
==============================================================================
--- directory/site/trunk/content/studio/developers-howtos/howtos/table-widget.mdtext (added)
+++ directory/site/trunk/content/studio/developers-howtos/howtos/table-widget.mdtext Wed Jul 1 08:45:49 2015
@@ -0,0 +1,477 @@
+Title: Table widget
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+# Table Widget
+
+It's sometime convenient to use a Table which is associated with a list of optionnally ordered elements, with Add/Edit/Delete actions, and up/down actions if the table is ordered. We have such a widget in _org.org.apache.directory.studio.common.ui.widgets_.
+
+The Table which will be exposed looks like this :
+
+ +--------------------------------------+
+ | Element 1 | (Add... )
+ | Element 2 | (Edit...)
+ | | (Delete )
+ +--------------------------------------+
+
+or this, if the element are ordered
+ +--------------------------------------+
+ | Element 1 | (Add... )
+ | Element 2 | (Edit...)
+ | | (Delete )
+ | | ---------
+ | | (Up )
+ | | (Down )
+ +--------------------------------------+
+
+Optionally, the _Edit_ button might be disabled.
+
+Clicking on an element will select it, so that one can delete it.
+
+Last, not least, double clicking on an element will edit it, if allowed. In this case, a dedicated Dialog will be opened.
+
+## Ordered table
+
+Here, we are not talking about the fact that the elements are ordered using some comparator, but the fact that the elements have an associated numeral prefix which is used to order the elements, regardeless of the element's content. This is an OpenLDAP extension, where elements are prefixed with a _{n}_ String, where 'n' is a vlaue between 0 to MAX_INTEGER (but it can also be -1, in one specific case).
+
+Bottom line, when a table is declared as Ordered, we use this prefix (which is shown) to order the elements in the tbale, otherwise we use the _compareTo_ method.
+
+## The Element requirements
+
+First of all, we have to focus on the elements. There are some requirements that such Objects much fulfill :
+
+* Either the element can be compared and cloned natively (like an Enum)
+* or it has to implement those methods (and the _Cloneable_ and _Comparable_ interfaces):
+ * clone
+ * hashCode
+ * equals
+ * compareTo
+ * toString
+
+
+The idea is to be able to find an element in the table using the _equals()_ method, to copy an element, and to order the table content.
+
+## How it works
+
+Basically, we assemble 5 different elements :
+ * A Table
+ * A listener to handle the actions on the table
+ * A Decorator to show the elements in the Table
+ * A Dialog to edit the elements, or to add them
+ * A Wrapper to hold the elements that are stored in the Table
+
+Let see with some examples
+
+### Table with Add/Edit/Delete, no dialog
+
+Internally, we store the data in a _List<E>_ where *E* is the element's type (_TableWidget_ is a generic class). The only thing you need to do when you want to use this widget is to add this code snippet :
+
+
+ /** A TableWidget containing some RootDSE elements */
+ private TableWidget<StringValueWrapper> rootDseTableWidget;
+ ...
+ // Instanciate the TableWidget, associated with a Decorator
+ rootDseTableWidget = new TableWidget<StringValueWrapper>(
+ new StringValueDecorator( composite.getShell(), Messages.getString( "OpenLDAPOptionsPage.RootDSE" ) ) );
+
+ // We want an Edit button, but no Up/Down buttons
+ rootDseTableWidget.createWidgetWithEdit( composite, toolkit );
+ rootDseTableWidget.getControl().setLayoutData( new GridData( SWT.FILL, SWT.NONE, true, false, 2, 1 ) );
+
+ // Associate a listener to this table
+ addModifyListener( rootDseTableWidget, rootDseTableListener );
+
+
+Here, we declare a _TableWidget_, a type of elements (StringValueWrapper), a label provider (used to decorate the elements in the table, if needed).
+
+Last, not least, you create the widget and set its position in your screen.
+
+### The element wrapper
+
+We need to wrap the element in the table in order to expose a few basic functions :
+ * clone
+ * hashCode
+ * equals
+ * compareTo
+ * toString
+
+Here is an exemple, the _StringValueWrapper_, which wrap a simple value, which is itself a String :
+
+ public class StringValueWrapper implements Cloneable, Comparable<StringValueWrapper>
+ {
+ /** The value */
+ private String value;
+
+ /** A flag to tell if the compare should be case sensitive or not */
+ private boolean caseSensitive = true;
+
+ /**
+ * Creates a new instance of StringValueWrapper.
+ *
+ * @param value the value
+ */
+ public StringValueWrapper( String value, boolean caseSensitive )
+ {
+ this.value = value;
+ this.caseSensitive = caseSensitive;
+ }
+
+
+ /**
+ * @return the value
+ */
+ public String getValue()
+ {
+ return value;
+ }
+
+ /**
+ * @param value the value to set
+ */
+ public void setValue( String value )
+ {
+ this.value = value;
+ }
+
+
+ /**
+ * Clone the current object
+ */
+ public StringValueWrapper clone()
+ {
+ try
+ {
+ return (StringValueWrapper)super.clone();
+ }
+ catch ( CloneNotSupportedException e )
+ {
+ return null;
+ }
+ }
+
+
+ /**
+ * @see Object#equals(Object)
+ */
+ public boolean equals( Object that )
+ {
+ // Quick test
+ if ( this == that )
+ {
+ return true;
+ }
+
+ if ( that instanceof StringValueWrapper )
+ {
+ StringValueWrapper thatInstance = (StringValueWrapper)that;
+
+ if ( caseSensitive )
+ {
+ return value.equals( thatInstance.value );
+ }
+ else
+ {
+ return value.equalsIgnoreCase( thatInstance.value );
+ }
+ }
+ else
+ {
+ return false;
+ }
+ }
+
+
+ /**
+ * @see Object#hashCode()
+ */
+ public int hashCode()
+ {
+ int h = 37;
+
+ if ( value != null )
+ {
+ h += h*17 + value.hashCode();
+ }
+
+ return h;
+ }
+
+
+ /**
+ * @see Comparable#compareTo()
+ */
+ public int compareTo( StringValueWrapper that )
+ {
+ if ( that == null )
+ {
+ return 1;
+ }
+
+ // Check the value
+ if ( Strings.isEmpty( value ) )
+ {
+ return -1;
+ }
+ else
+ {
+ return value.compareToIgnoreCase( that.value );
+ }
+ }
+
+
+ /**
+ * @see Object#toString()
+ */
+ public String toString()
+ {
+ return value;
+ }
+ }
+
+Of course, your implementation may be way more complex, but all in all, the API contract is the same.
+
+### The Decorator
+
+This is just a class that extends the _TableDecorator_ abstract class. The _TableDecorator_ extendss the _LabelProvider_ class and implements the _Comparator_ interface.
+
+Here is an example :
+
+ public class StringValueDecorator extends TableDecorator<StringValueWrapper>
+ {
+ /**
+ * Create a new instance of StringValueDecorator
+ * @param parentShell The parent Shell
+ * @param attributeName the name of the attribute which will contain the value
+ */
+ public StringValueDecorator( Shell parentShell, String attributeName )
+ {
+ setDialog( new StringValueDialog( parentShell, attributeName ) );
+ }
+
+
+ /**
+ * Construct the label for a String.
+ * @param element the Element for which we want the value
+ * @return a String representation of the element
+ */
+ public String getText( Object element )
+ {
+ if ( element instanceof StringValueWrapper )
+ {
+ return ( ( StringValueWrapper ) element ).getValue();
+ }
+
+ return super.getText( element );
+ };
+
+
+ /**
+ * Get the image. We have none
+ * @param element The element for which we want the image
+ * @return The associated Image, or Null
+ */
+ public Image getImage( Object element )
+ {
+ return null;
+ };
+
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public int compare( StringValueWrapper e1, StringValueWrapper e2 )
+ {
+ if ( e1 != null )
+ {
+ if ( e2 == null )
+ {
+ return 1;
+ }
+ else
+ {
+ return e1.compareTo( e2 );
+ }
+ }
+ else
+ {
+ if ( e2 == null )
+ {
+ return 0;
+ }
+ else
+ {
+ return 1;
+ }
+ }
+ }
+ }
+
+Here, each line in the Table will represent an instance of a _WtringValueWrapper_, with no image. Would you need to add an image before the text, it's just a matter to return this image in the _getImage()_ method.
+
+The constructor takes 2 arguments, the second one will be used in the default Dialog we use to create new String values.
+
+The text is simply constructed using the _toString()_ method, but you may use whatever fits your need.
+
+### The Dialog
+
+This is the complex part, which totally depends on what you want to do. In any case, all the User's Dialog will inherit from the _AddEditDialog_ class, which defines some default actions.
+
+Here is a quick description of this abstract class :
+
+ AddEditDialog<E> extends Dialog
+
+ fields :
+ E editedElement : The element that is edited, if one clicked on the Edit button, or the new element to create for the Add action
+ List<E> elements : The list of elements already in the Table
+ int selectedPosition : If an element has been selected in the Table, contain its position in the _elements_ list
+ boolean isAdd : A flag set to true if the Add button has been clicked.
+ boolean okDisabled : A flag to tell if the OK button has to be disabled (for instance, if the data are invalid while creating or editing an element)
+
+ abstract methods :
+ void addNewElement() : If the Add button is clicked, we ask the specific Dialog to create an empty instance of Element. This method has to be implemented.
+ void initDialog() : read the wrapped element into the dialog's Widgets
+
+
+ public methods :
+ E getEditedElement() : Get the element that is currently being edited.
+ int getSelectedPosition() : Get the selected position, if any
+ boolean isAdd() : Tells if the element is an addition or an edition
+ void setAdd() : This is an Addition
+ void setEdit() : This is an Edition
+ void setEditedElement( E editedElement ) : Set the element that will be edited. Actually, a new instance is created, that will contain a copy of the edited element.
+ void setElements( List<E> elements ) : Keep a copy (not shallow) of the Table content.
+ void setSelectedPosition( int selectedPosition ) : Store the selected position
+
+ protected methods :
+ Control createButtonBar( Composite parent ) : Used to hide the OK button if needed
+ List<E> getElements() : Returns the list of elements
+ void initDialog() : Can be overloaded if the Dialog needs to inject an edited element in the Dialog widgets. Optional.
+
+You generally have to implement the _addNewElement()_ and _initDialog()_ methods in your own Dialog class, then implement all the logic to render your dialog.
+
+Here is how you set up your Dialog instance :
+
+ protected Control createDialogArea( Composite parent )
+ {
+ Composite composite = ( Composite ) super.createDialogArea( parent );
+ GridData gd = new GridData( GridData.FILL_BOTH );
+ composite.setLayoutData( gd );
+
+ // StringValue Group
+ Group stringValueGroup = BaseWidgetUtils.createGroup( parent, null, 1 );
+ GridLayout stringValueGroupGridLayout = new GridLayout( 2, false );
+ stringValueGroup.setLayout( stringValueGroupGridLayout );
+ stringValueGroup.setLayoutData( new GridData( SWT.FILL, SWT.NONE, true, false ) );
+
+ // String Text
+ BaseWidgetUtils.createLabel( stringValueGroup, attributeName + ":", 1 );
+ stringValue = BaseWidgetUtils.createText( stringValueGroup, "", 1 );
+ stringValue.setLayoutData( new GridData( SWT.FILL, SWT.NONE, true, false ) );
+
+ initDialog();
+ addListeners();
+
+ applyDialogFont( composite );
+
+ return composite;
+ }
+
+Here is what you'll get on the screen when an element is selected :
+
+ +---------------------------------------+
+ | .-----------------------------------. |
+ | | Value : [ ] | |
+ | '-----------------------------------' |
+ | |
+ | (cancel) (OK) |
+ +---------------------------------------+
+
+The rendering can be way more complex though.
+
+### Actions
+
+There are two, three, four or five possible actions on this table :
+* Add
+* Edit (optional)
+* Delete
+* Up (optional)
+* Down (optional)
+
+Let's see how it works.
+
+#### Add action
+
+We will open the Dialog that is provided, and get back a new element which will be exposed in the Table. We also will check that the element is not already present, and if so, no duplicate will be added, except if the table is ordered.
+
+If the table is not ordered, the newly created element will be injected at the right place in the Table : we use the _compareTo_ method to find the position it as to be added in. If the element already exists, it's not added.
+
+If the table is ordered, this is a different story :
+* there is a selected element : the newly created element is added _after_ the selection, and all the following elements' prefix are incremented.
+* we don't have any selected element : the newly created element is added at the end of the Table, and its prefix is the laset element's prefix, plus one.
+
+#### Delete action
+
+The delete action only works for a selected element.
+
+If the Table is ordered, we will update the prefix of the elements after the deleted one, decrementing all of them.
+
+#### Edit action
+
+The edition of an element will replace the selected element by its new value.
+
+If the Table is ordered, the prefix will not be changed. Otherwise, the edited element might be moved to another position, depending on where it fits accordingly to the _compareTo_ method.
+
+#### Up Action
+
+The Up action will move one element up in the table. It's only valid for an ordered Table. Basically, it does nothing more than just exchanging two elements, and sapping their prefix.
+
+#### Down action
+
+The Up action will move one element down in the table. It's only valid for an ordered Table. Basically, it does nothing more than just exchanging two elements, and sapping their prefix.
+### The listener
+
+Last, not least, we have to add a Listener to react on what happens on the table itself.
+
+It's all about post-modification actions. In our case, we want to update the underlaying OpenLDAP configuration :
+
+ private WidgetModifyListener rootDseTableListener = new WidgetModifyListener()
+ {
+ public void widgetModified( WidgetModifyEvent e )
+ {
+ List<String> rootDses = new ArrayList<String>();
+
+ for ( StringValueWrapper rootDse : rootDseTableWidget.getElements() )
+ {
+ rootDses.add( rootDse.getValue() );
+ }
+
+ getConfiguration().getGlobal().setOlcRootDSE( rootDses );
+ }
+ };
+
+But it can be hatever fits your need.
+## Creating a Table with no edit button, or an Ordered table
+
+We have seen how to create a Table with an Edit button. Creating teh other Table's flawors is easy :
+
+* With edit : TableWidget.createWidgetWithEdit( Composite, FormToolkit );
+* No edit : TableWidget.createWidgetNoEdit( Composite, FormToolkit );
+* Ordered, No edit : TableWidget.createOrderedWidgetNoEdit( Composite, FormToolkit );
+* Ordered, with edit : TableWidget.createOrderedWidgetWithEdit( Composite, FormToolkit );
+
+Everything else is the same.
\ No newline at end of file