Chapter 2. Commands

Chapter 2. Commands
	Part I. Commands

Table of Contents

1. The prepare and execute methods

1.1. A very simple, sample command

2. Making a command repeatable and recordable

What is a command?

A command is some code which acts on a DocumentView

by changing the text or node selection,
and/or by modifying the underlying Document rendered using this DocumentView,
and/or by modifying the contents of the system clipboard.

The selection is specified by Marks attached to Document Nodes which are managed by a MarkManager. There are 4 standard marks:

dot: Its visual representation is called the caret (or the insertion cursor). It is a small vertical line which blinks (when the DocumentView has the keyboard focus).
mark: Text between dot and mark is selected. This text selection is painted over a pink background.
selected: The node to which this mark is attached is the selected node. It is displayed with a thin red line around it.
selected2: This mark can only be attached to a sibling of the selected node (therefore this mark is absent if the selected mark is absent). The node range marked by selected and selected2 is the selected node range. Each node in the selected range is displayed with a thin red line around it. This type of selection is really a generalization of single node selection.

Note that any of these marks, even dot, may be absent.

Where to declare a command?

All built-in commands (selectAt, insert, paste, etc) are automatically registered with the command registry associated to the DocumentView.

Any other command must be declared in a configuration file, either one of the user's customize.xxe files or the configuration file associated to a document type (docbook.xxe, topic.xxe, etc) by the means of the command configuration element in XMLmind XML Editor - Configuration and Deployment. Example (excerpts from docbook.xxe):

<command name="docb.olinkedDocuments">
  <class>com.xmlmind.xmleditext.docbook.OlinkedDocuments</class>
</command>

Commands may also be declared in XXE GUI specifications (.xxe_gui files) by the means of the command GUI specification element in XMLmind XML Editor - Customizing the User Interface, but this is uncommon. Example (excerpts from DesktopApp.xxe_gui):

<command name="XXE.new">
  <class>com.xmlmind.xmleditapp.desktop.file.NewCmd</class>
</command>

How to implement a command?

Extend abstract class CommandBase, that is, implement a constructor invoking the CommandBase constructor and also the prepare and doExecute methods. Example:

public class ConvertCaseCmd extends CommandBase {
    ...  
    public ConvertCaseCmd() {
        super(/*repeatable*/ false, /*recordable*/ true);
    }

    public boolean prepare(DocumentView docView, 
                           String parameter, int x, int y) { ... }

    public CommandResult doExecute(DocumentView docView, 
                                   String parameter, int x, int y) { ... }
}

Abstract class CommandBase implements low-level interface Command. However unlike Command which acts on Gadget, which are low-level visual objects, CommandBase acts on the DocumentView itself and if needed to, also automatically registers executed command with the command history (can be used by the means of commands repeat in XMLmind XML Editor - Commands and listRepeatable in XMLmind XML Editor - Commands) and with the command macro-recorder (can be used by the means of command recordMacro in XMLmind XML Editor - Commands).