Blame - examples/org.eclipse.graphiti.doc/resources/docu/gfw/direct-editing-feature.htm - graphiti/org.eclipse.graphiti

2011-07-21 12:36:20 +0000

[diff] [blame]

1

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

2

<html>

mwenz

2010-06-16 13:24:52 +0000

[diff] [blame]

3

4

<head>

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

5

mwenz

2010-06-16 13:24:52 +0000

[diff] [blame]

6

<title>Providing direct editing functionality</title>

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

7

8

mwenz

2010-06-16 13:24:52 +0000

[diff] [blame]

9

</head>

10

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

11

<body>

mwenz

2010-06-16 13:24:52 +0000

[diff] [blame]

12

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

13

<h1>Providing Direct Editing Functionality</h1>

14

Direct editing means the possibility to change values directly in the graphical

15

editor. Technically the user clicks on a pictogram-element and an editor is shown,

16

where the user can change the values of this pictogram element.

17

A typical use case is, that the user clicks on a text (either in a shape or a

18

connection decorator) and then the text is overlaid with a text-edit-field, where

19

the user can change the text value. To the user this actually looks as if the text

20

is replaced with the text-edit-field.

21

jpasch

da3428a

2012-05-25 11:10:26 +0200

[diff] [blame^]

22

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

23

Figure: Direct editing of a text

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

24

<h2>Creating a Direct Editing Feature</h2>

25

In this example we want to enable the users to edit the name of a EClass directly

26

in the diagram. Therefore we have to create a direct editing feature and make it

27

available in the feature provider. A direct editing feature has to implement the

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

28

interface

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

29

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

30

IDirectEditingFeature</a>. Instead of implementing it directly it should extend

31

one of the available base classes. In this example we extend the base class

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

32

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

33

AbstractDirectEditingFeature</a>.

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

34

35

In this case we have to implement/overwrite several methods:

<ul>

<li>The method

getEditingType</a> has to return the editor type which shall be used to edit

40

the value, in this example a text editor.</li>

41

<li>The method

42

43

canDirectEdit</a> has to check the given context and therefore it decides if

44

direct editing is supported.</li>

45

<li>The method

46

47

getInitialValue</a> has to return the initial value with which the editor is

48

initialized, which is usually the currently displayed value.</li>

49

<li>The method

50

51

checkValueValid</a> performs a check of the current editor value on each value

change.</li>

<li>The method

setValue</a> has to set the edited value to the model at the end of the editing

56

process.</li>

57

</ul>

58

You can see the complete implementation of the direct editing feature here:

59

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

60

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

61

62

63

package org.eclipse.graphiti.examples.tutorial.features;

64

public class TutorialDirectEditEClassFeature

65

extends     AbstractDirectEditingFeature

66

{       public TutorialDirectEditEClassFeature(IFeatureProvider

67

fp) {

68

super(fp);     }

69

public int getEditingType() {

70

// there are several possible editor-types supported:

71

// text-field, checkbox, color-chooser, combobox, ...

72

return TYPE_TEXT;

73

}       @Override

74

public boolean canDirectEdit(IDirectEditingContext

75

context) {         PictogramElement

76

pe = context.getPictogramElement();

77

Object bo = getBusinessObjectForPictogramElement(pe);

78

GraphicsAlgorithm ga = context.getGraphicsAlgorithm();

79

// support direct editing, if it is a EClass, and

80

the user clicked         // directly

81

on the text and not somewhere else in the rectangle

82

if (bo instanceof

83

EClass && ga instanceof Text) {

84

return true;

85

}         //

86

direct editing not supported in all other cases

87

return false;     }

88

public String getInitialValue(IDirectEditingContext

89

context) {

90

// return the current name of the EClass

91

PictogramElement pe = context.getPictogramElement();

92

EClass eClass = (EClass) getBusinessObjectForPictogramElement(pe);

93

return eClass.getName();

94

}       @Override

95

public String checkValueValid(String value,

96

IDirectEditingContext context) {

97

if (value.length() < 1)

98

return "Please enter any

99

text as class name.";

100

if (value.contains(" "))

101

return "Spaces are not

102

allowed in class names.";

103

if (value.contains("\n"))

104

return "Line breakes are

105

not allowed in class names.";

106

// null means, that the value is valid

107

return null;     }

108

public void setValue(String value, IDirectEditingContext

109

context) {

jpasch

b3fc719

2011-08-18 11:16:33 +0200

[diff] [blame]

110

// set the new name for the EClass

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

111

PictogramElement pe = context.getPictogramElement();

112

EClass eClass = (EClass) getBusinessObjectForPictogramElement(pe);

113

eClass.setName(value);

114

// Explicitly update the shape to display the new

115

value in the diagram         // Note,

116

that this might not be necessary in future versions of Graphiti

117

// (currently in discussion)

118

// we know, that pe is the Shape of the Text, so its

119

container is the         // main shape

120

of the EClass         updatePictogramElement(((Shape)

121

pe).getContainer());     } }

122

</div>

mwenz

2010-06-16 13:24:52 +0000

[diff] [blame]

123

</div>

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

124

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

125

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

126

Additionally the feature provider has to deliver our newly created feature (overwrite

127

the method

128

129

getDirectEditingFeature</a>). This implementation can be seen here:

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

130

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

@Override public IDirectEditingFeature

135

getDirectEditingFeature(     IDirectEditingContext context)

136

{     PictogramElement pe = context.getPictogramElement();

137

Object bo = getBusinessObjectForPictogramElement(pe);

138

if (bo instanceof

139

EClass) {

140

return new TutorialDirectEditEClassFeature(this);

141

}     return super.getDirectEditingFeature(context);

}

</div>

</div>

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

146

147

<h2>Test: Edit the Name of a Class Directly In the Diagram</h2>

jpasch

2011-06-30 13:44:46 +0000

[diff] [blame]

148

Now start the editor and test this new direct editing feature:

149

<ol>

150

<li>Create or open a  diagram and create an EClass "Address"</li>

151

<li>Click on the class name and the value "Address" should become editable in

152

the text-editor</li>

153

<li>Change the value to "Customer Address". Now the editor should be highlighted

154

and an error-message ("no space allowed") should be displayed in the status-bar.</li>

155

<li>Change the value to "CustomerAddress". The highlight and error-message should

156

disappear. </li>

157

<li>Press return or make the editor loose focus otherwise to overtake the edited

158

value, or press ESC to cancel the editing.</li>

159

</ol>

jpasch

2011-07-21 12:36:20 +0000

[diff] [blame]

160

mwenz