Writing a Command Class

.NET Customisation User Guide

.NET Customisation : How to Write a CAF Addin : Addin Commands : Writing a Command Class

The example below is for a simple command class used to manage the visibility state of a docked window, in this case the AttributeBrowser docked window. The CAF provides an abstract base class from which every Command class must inherit. The constructor for a Command class should set the base class Key property which is used to reference the command from within a UIC file.

The Command base class has the following methods and properties which can be overridden by a derived Command class.

void Execute(): This method must be overridden to provide the command execution functionality.

Optionally you can specify a collection of arguments to the execute method:

void Execute(ArrayList arguments): This will automatically use the correct overload of Execute() which matches the argument types given in the ArrayList. If no match is found then nothing is called. You can use the support property Executes to obtain a list of valid Execute() overloads and the method FindExecute(ArrayList arguments, out MethodInfo info) to determine if an argument list matches an overload.

CommandState GetState(): This method is called by the CAF to update the state of the contents of a context menu. The returned value is a CommandState enumeration for various states of a command. This enumeration can be treated as a bit field; that is, a set of flags. Bit fields can be combined using a bitwise OR operation. The command state is then reflected by the user interface.

String Description: A description for the command.

void Refresh(string context): This method will be called whenever the CommandManager.ApplicationContext property is changed. This gives the command the opportunity to update its Enabled or Visible state in response to this context change. This command state change would then be reflected in the user interface.

The Command base class also has a number of properties which are use to update the command state following user interface changes or vice-versa.

bool Checked: If associated with a user interface entity such as a StateButtonTool then this property and the corresponding state of the user interface entity are kept synchronised.

bool Enabled: Changes to this property are reflected in all associated user interface entities.

ArrayList List: This property allows a command to communicate a list of string values to the user interface. This can be used when a command is associated with for example a ComboBoxTool.

int SelectedIndex: This property is updated to indicate which item from a list has been selected by the user.

object Value: This property holds the currently value of an associated user interface entity.

bool ValueChanged: Before calling the execute method the CAF sets this property if the value of the user interface entity has changed. The flag is cleared when execution has finished.

bool Visible: Changes to this property are reflected in all associated user interface entities.

Registering a command with the CAF is done by adding an instance of a command class to the CommandManagers.Commands collection.

ShowAttributeBrowserCommand showCommand = new      ShowAttributeBrowserCommand(attributeListWindow);

commandManager.Commands.Add(showCommand);

//Copyright 1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved in original code only.

using System;

using System.Collections.Generic;

using System.Text;

using Aveva.ApplicationFramework.Presentation;

namespace Aveva.Core.Samples

{

    /// <summary>

    /// Class to manage the visibility state of the AttributeBrowser docked window

    /// This command should be associated with a StateButtonTool.

    /// </summary>

    public class ShowAttributeBrowserCommand : Command

{

        private DockedWindow _window;

        /// <summary>

        /// Constructor for ShowAttributeBrowserCommand

        /// </summary>

        /// <param name="window">The docked window whose visibility state will be managed.</param>

        public ShowAttributeBrowserCommand(DockedWindow window)

{

            // Set the command key

            this.Key = "Aveva.ShowAttributeBrowserCommand";

            // Save the docked window

            _window = window;

            // Create an event handler for the window closed event

            _window.Closed += new EventHandler(_window_Closed);

            // Create an event handler for the WindowLayoutLoaded event

	Aveva.ApplicationFramework.DependencyResolver.GetImplementationOf<WindowlayoutLoaded += new EventHandler(Instance_WindowsLayoutLoaded);

}

        void Instance_WindowLayoutLoaded(object sender, EventArgs e)

{

            // Update the command state to match initial window visibility

            this.Checked = _window.Visible;

}

        void _window_Closed(object sender, EventArgs e)

{

            // Update the command state when the window is closed

            this.Checked = false;

}

        /// <summary>

        /// Override the base class Execute method to show and hide the window

        /// </summary>

        public override void Execute()

{

            if (this.Checked)

{

                _window.Show();

}

            else

{

                _window.Hide();

}

}

}

}