Refresh Windows

Context

Most windows do not merely show model elements; they also enable their changes. These changes normally affect both the window which the change was made in and the other windows as well. e.g. if the name of an open diagram is changed in the model tree, the text in the diagram's tab and the name field in the Properties window also need to be modified. This means that the window which changes to model elements were made in needs to inform the other windows about the action. The Refresh message can be used for this.

WindowMessageType.Refresh

A Refresh message contains data of the RefreshWindowMessage type. The data contains information about the type of refresh.

• Mode from the RefreshMode type

  Type of refresh

• ElSet from the ElementSet type

  Model elements affected by refresh

Mode	Triggering Action	ElSet
Command	The Reload Contents command was triggered.	Empty set
Content1	Old window contents was made visible.	Empty set
Create	Model elements were created.	Created elements
AddDiagramGraphic	Model elements were added to a diagram.	Added elements
Delete2	Model elements were deleted.	Deleted Elements
ChangeName	Changes to a name	Element affected
ChangeStereoM2Attribute	Changes to properties	Elements affected
ChangeStereoProperty	Changes to stereotype properties	Elements affected
ChangeLabel	Changes to labels	Elements affected
ChangeSpecification	Changes to specification texts	Element affected
ChangePicture	Changes to an assigned picture	Element affected
ChangeOrder	Changes to the order of assigned elements	Element affected
ChangeImportedProfiles	Changes to imported profiles for packages	Packages affected
ChangeAccess	Changes to access rights	Elements affected
ChangeContainer	Container change	Elements affected
ChangeLock	Changes to locking state	Elements affected; empty set when unlocking all elements
ChangeApplicationConfiguration	Changes to a Application Configuration (data contains the purpose)	Element affected

¹ A tool window does not get any Refresh messages if it is not visible. A flag saying that the window was not refreshed and that its contents is probably old is set instead. If the window is activated, a Refresh message with the Content mode is triggered. The tool window should then fully refresh its contents.

² For RefreshMode.Delete mode please note that the deleted elements may be in the message's information but these are already deleted and no longer valid. No properties of these elements can be accessed. The element set can only be used to e.g. search for the elements affected in the window to decide whether the window is affected by the delete action.

RefreshModel Methods

You need to send Refresh messages to other windows if you make changes to model elements. Element modification is therefore normally carried out as follows:

• The change is made in a window control or in a dialog and applied.

• Applying sends the change to the server using a call of a respective method of the server API.

• If the server reports an error this is shown in a message box. The window and/or dialog returns to the state it was in immediately prior to applying the changes once the message box has been closed. i.e. the control element still contains the modified data.

• If the server returns a reply that the changes have been transferred with no errors, a Refresh message needs to be sent to all windows so they can update their contents if necessary by processing the Refresh message in their MessageHandler method.

  Use the RefreshModel method for sending messages.

Window Refreshes Following Creation of Elements

The described procedure for a window refresh is insufficient if there is a requirement for creating further - usually dependent - elements during the creation of elements. This special case is solved by the following procedure:

• Following the creation of new elements, the RefreshModel method is not called to refresh the windows; instead, ExecuteCreateRefresh is called. This method contains the newly created elements and their owners (optional) as parameters.

• The method sends a message of the ElementsCreated type with data of the ElementsCreatedWindowMessage type. This contains the newly created elements and their owners and a property for the return of the CreatedElementsInfo type.

• A plug-in can itself create further elements during the processing of this message. The new elements must then be inserted into the return property with a CreatedElementsInfo.Add method.

• Once all windows have processed the message, the return property might contain further pairs of newly created elements and their owners. These are processed by further ElementsCreated messages until no further new elements are created. This means that the creation of dependent elements is also possible recursively.

• Following the collection of the new elements and their owners, a single window refresh with the RefreshMode.Create type is triggered. The message data contains a property of the CreatedElementsRefreshInfo type that contains all created elements (as logics) and their owners.