Add event handlers to Form/Group/Field

formsfx-core/src/main/java/com/dlsc/formsfx/model/event/FieldEvent.java

@@ -0,0 +1,67 @@
+package com.dlsc.formsfx.model.event;
+
+/*-
+ * ========================LICENSE_START=================================
+ * FormsFX
+ * %%
+ * Copyright (C) 2017 - 2018 DLSC Software & Consulting
+ * %%
+ * Licensed 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.
+ * =========================LICENSE_END==================================
+ */
+
+import com.dlsc.formsfx.model.structure.Field;
+import javafx.event.Event;
+import javafx.event.EventType;
+
+/**
+ * Identifies events triggered by a {@code Field}.
+ *
+ * @author Andres Almiray
+ */
+public final class FieldEvent extends Event {
+    /**
+     * When a {@code Field} is persisted.
+     */
+    public static final EventType<FieldEvent> EVENT_FIELD_PERSISTED = new EventType<>(ANY, "EVENT_FIELD_PERSISTED");
+
+    /**
+     * When a {@code Field} is reset.
+     */
+    public static final EventType<FieldEvent> EVENT_FIELD_RESET = new EventType<>(ANY, "EVENT_FIELD_RESET");
+
+    /**
+     * Creates a new instance of {@code FieldEvent} with event type set to {@code EVENT_FIELD_PERSISTED}.
+     */
+    public static FieldEvent fieldPersistedEvent(Field field) {
+        return new FieldEvent(EVENT_FIELD_PERSISTED, field);
+    }
+
+    /**
+     * Creates a new instance of {@code FieldEvent} with event type set to {@code EVENT_FIELD_RESET}.
+     */
+    public static FieldEvent fieldResetEvent(Field field) {
+        return new FieldEvent(EVENT_FIELD_RESET, field);
+    }
+
+    private final Field field;
+
+    private FieldEvent(EventType<? extends Event> eventType, Field field) {
+        super(eventType);
+        this.field = field;
+    }
+
+    public final Field getField() {
+        return field;
+    }
+}

formsfx-core/src/main/java/com/dlsc/formsfx/model/event/FormEvent.java

@@ -0,0 +1,67 @@
+package com.dlsc.formsfx.model.event;
+
+/*-
+ * ========================LICENSE_START=================================
+ * FormsFX
+ * %%
+ * Copyright (C) 2017 - 2018 DLSC Software & Consulting
+ * %%
+ * Licensed 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.
+ * =========================LICENSE_END==================================
+ */
+
+import com.dlsc.formsfx.model.structure.Form;
+import javafx.event.Event;
+import javafx.event.EventType;
+
+/**
+ * Identifies events triggered by a {@code Form}.
+ *
+ * @author Andres Almiray
+ */
+public final class FormEvent extends Event {
+    /**
+     * When a {@code Form} is persisted.
+     */
+    public static final EventType<FormEvent> EVENT_FORM_PERSISTED = new EventType<>(ANY, "EVENT_FORM_PERSISTED");
+
+    /**
+     * When a {@code Form} is reset.
+     */
+    public static final EventType<FormEvent> EVENT_FORM_RESET = new EventType<>(ANY, "EVENT_FORM_RESET");
+
+    /**
+     * Creates a new instance of {@code FormEvent} with event type set to {@code EVENT_FORM_PERSISTED}.
+     */
+    public static FormEvent formPersistedEvent(Form form) {
+        return new FormEvent(EVENT_FORM_PERSISTED, form);
+    }
+
+    /**
+     * Creates a new instance of {@code FormEvent} with event type set to {@code EVENT_FORM_RESET}.
+     */
+    public static FormEvent formResetEvent(Form form) {
+        return new FormEvent(EVENT_FORM_RESET, form);
+    }
+
+    private final Form form;
+
+    private FormEvent(EventType<? extends Event> eventType, Form form) {
+        super(eventType);
+        this.form = form;
+    }
+
+    public final Form getForm() {
+        return form;
+    }
+}

formsfx-core/src/main/java/com/dlsc/formsfx/model/event/GroupEvent.java

@@ -0,0 +1,67 @@
+package com.dlsc.formsfx.model.event;
+
+/*-
+ * ========================LICENSE_START=================================
+ * FormsFX
+ * %%
+ * Copyright (C) 2017 - 2018 DLSC Software & Consulting
+ * %%
+ * Licensed 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.
+ * =========================LICENSE_END==================================
+ */
+
+import com.dlsc.formsfx.model.structure.Group;
+import javafx.event.Event;
+import javafx.event.EventType;
+
+/**
+ * Identifies events triggered by a {@code Group}.
+ *
+ * @author Andres Almiray
+ */
+public final class GroupEvent extends Event {
+    /**
+     * When a {@code Group} is persisted.
+     */
+    public static final EventType<GroupEvent> EVENT_GROUP_PERSISTED = new EventType<>(ANY, "EVENT_GROUP_PERSISTED");
+
+    /**
+     * When a {@code Group} is reset.
+     */
+    public static final EventType<GroupEvent> EVENT_GROUP_RESET = new EventType<>(ANY, "EVENT_GROUP_RESET");
+
+    /**
+     * Creates a new instance of {@code GroupEvent} with event type set to {@code EVENT_GROUP_PERSISTED}.
+     */
+    public static GroupEvent groupPersistedEvent(Group group) {
+        return new GroupEvent(EVENT_GROUP_PERSISTED, group);
+    }
+
+    /**
+     * Creates a new instance of {@code GroupEvent} with event type set to {@code EVENT_GROUP_RESET}.
+     */
+    public static GroupEvent groupResetEvent(Group group) {
+        return new GroupEvent(EVENT_GROUP_RESET, group);
+    }
+
+    private final Group group;
+
+    private GroupEvent(EventType<? extends Event> eventType, Group group) {
+        super(eventType);
+        this.group = group;
+    }
+
+    public final Group getGroup() {
+        return group;
+    }
+}

formsfx-core/src/main/java/com/dlsc/formsfx/model/structure/DataField.java

@@ -20,6 +20,7 @@
  * =========================LICENSE_END==================================
  */
 
+import com.dlsc.formsfx.model.event.FieldEvent;
 import com.dlsc.formsfx.model.util.BindingMode;
 import com.dlsc.formsfx.model.util.TranslationService;
 import com.dlsc.formsfx.model.util.ValueTransformer;
@@ -262,6 +263,8 @@ public void persist() {
         }
 
         persistentValue.setValue(value.getValue());
+
+        fireEvent(FieldEvent.fieldPersistedEvent(this));
     }
 
     /**
@@ -274,6 +277,8 @@ public void reset() {
         }
 
         userInput.setValue(String.valueOf(persistentValue.getValue()));
+
+        fireEvent(FieldEvent.fieldResetEvent(this));
     }
 
     /**

formsfx-core/src/main/java/com/dlsc/formsfx/model/structure/Field.java

@@ -20,6 +20,7 @@
  * =========================LICENSE_END==================================
  */
 
+import com.dlsc.formsfx.model.event.FieldEvent;
 import com.dlsc.formsfx.model.util.BindingMode;
 import com.dlsc.formsfx.model.util.TranslationService;
 import com.dlsc.formsfx.view.controls.SimpleControl;
@@ -38,13 +39,18 @@
 import javafx.beans.property.StringProperty;
 import javafx.collections.FXCollections;
 import javafx.collections.ObservableList;
+import javafx.event.EventHandler;
+import javafx.event.EventType;
 import javafx.scene.Node;
 import javafx.scene.control.Label;
 import javafx.scene.control.Labeled;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.stream.Collectors;
 
 /**
@@ -145,6 +151,8 @@ public abstract class Field<F extends Field> {
 
     protected SimpleControl<F> renderer;
 
+    protected final Map<EventType<FieldEvent>,List<EventHandler<? super FieldEvent>>> eventHandlers = new ConcurrentHashMap<>();
+
     /**
      * With the continuous binding mode, values are always directly persisted
      * upon any changes.
@@ -858,6 +866,68 @@ public ListProperty<String> errorMessagesProperty() {
         return errorMessages;
     }
 
+    /**
+     * Registers an event handler to this field. The handler is called when the
+     * field receives an {@code Event} of the specified type during the bubbling
+     * phase of event delivery.
+     *
+     * @param eventType    the type of the events to receive by the handler
+     * @param eventHandler the handler to register
+     *
+     * @throws NullPointerException if either event type or handler are {@code null}.
+     */
+    public Field addEventHandler(EventType<FieldEvent> eventType, EventHandler<? super FieldEvent> eventHandler) {
+        if (eventType == null) {
+            throw new NullPointerException("Argument eventType must not be null");
+        }
+        if (eventHandler == null) {
+            throw new NullPointerException("Argument eventHandler must not be null");
+        }
+
+        this.eventHandlers.computeIfAbsent(eventType, k -> new CopyOnWriteArrayList<>()).add(eventHandler);
+
+        return this;
+    }
+
+    /**
+     * Unregisters a previously registered event handler from this field. One
+     * handler might have been registered for different event types, so the
+     * caller needs to specify the particular event type from which to
+     * unregister the handler.
+     *
+     * @param eventType    the event type from which to unregister
+     * @param eventHandler the handler to unregister
+     *
+     * @throws NullPointerException if either event type or handler are {@code null}.
+     */
+    public Field removeEventHandler(EventType<FieldEvent> eventType, EventHandler<? super FieldEvent> eventHandler) {
+        if (eventType == null) {
+            throw new NullPointerException("Argument eventType must not be null");
+        }
+        if (eventHandler == null) {
+            throw new NullPointerException("Argument eventHandler must not be null");
+        }
+
+        List<EventHandler<? super FieldEvent>> list = this.eventHandlers.get(eventType);
+        if (list != null) {
+            list.remove(eventHandler);
+        }
+
+        return this;
+    }
+
+    protected void fireEvent(FieldEvent event) {
+        List<EventHandler<? super FieldEvent>> list = this.eventHandlers.get(event.getEventType());
+        if (list == null) {
+            return;
+        }
+        for (EventHandler<? super FieldEvent> eventHandler : list) {
+            if (!event.isConsumed()) {
+                eventHandler.handle(event);
+            }
+        }
+    }
+
     public Node getLabelDescription() {
         return labelDescription;
     }