From 89cbf4abe1fa0f9ba37d64b1d77f57e620693bad Mon Sep 17 00:00:00 2001 From: Robin Cheney Date: Sun, 23 Nov 2025 10:04:50 +0100 Subject: [PATCH] display modifications and comments --- .../tankstelle/FuelType.java | 10 +- .../controllers/FuelStationUIController.java | 24 +++ .../controllers/NewStationTabController.java | 27 +++- .../controllers/OverviewTabController.java | 144 +++++++++++++++++- .../controllers/PriceTabController.java | 20 ++- .../controllers/ResultTabController.java | 27 +++- .../controllers/SearchTabController.java | 15 +- .../controllers/StockTabController.java | 18 ++- .../UnderstaffedTabController.java | 15 +- 9 files changed, 289 insertions(+), 11 deletions(-) diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/FuelType.java b/src/main/java/de/diejungsvondertanke/tankstelle/FuelType.java index 31e1fde..0912284 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/FuelType.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/FuelType.java @@ -22,7 +22,7 @@ public enum FuelType { /** * Fancy premium diesel */ - PREMIUM_DIESEL("Premium Diesel"), + PREMIUM_DIESEL("Premium diesel"), /** * Gas, Gas, Gas, I'm gonna step on the gas */ @@ -33,4 +33,12 @@ public enum FuelType { private FuelType(String name) { this.name = name; } + + /** + * Use this to get a reasonable display name out of the fuel types + */ + @Override + public String toString() { + return name; + } } diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/FuelStationUIController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/FuelStationUIController.java index 4757243..6be6532 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/FuelStationUIController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/FuelStationUIController.java @@ -20,6 +20,9 @@ import javafx.scene.layout.VBox; /** * Main controller class + * + * @author Sergej Pavlenko + * @author Robin Cheney */ public class FuelStationUIController { @@ -148,6 +151,12 @@ public class FuelStationUIController { controllerConsumer.accept(controller); } + /** + * Get the {@link FuelStation} selected in the Drop-Down list at the top left of + * the screen + * + * @return the selected fuel station or {@code null} if none selected + */ public FuelStation getSelectedStation() { int idx = comboFuelStations.getSelectionModel().getSelectedIndex(); if (idx < 0 || idx >= Main.fuelStations.size()) @@ -155,6 +164,10 @@ public class FuelStationUIController { return Main.fuelStations.get(idx); } + /** + * Refresh all station displays. MUST BE CALLED WHEN UPDATING ANYTHING, OR + * OTHERWISE NOT EVERYTHING WILL BE DISPLAYED UP-TO-DATE EVERYWHERE + */ @FXML public void refreshStationNames() { comboFuelStations.getItems().setAll( @@ -180,10 +193,21 @@ public class FuelStationUIController { return fs.getSimpleName(); } + /** + * Append the {@code text} to the output dialogue (with two linebreaks appended) + * + * @param text Text to put out + */ public void appendOutput(String text) { outputArea.appendText(text + "\n\n"); } + /** + * Display an error window to inform the user of invalid input, or something + * else. Depends on the content of {@code msg} + * + * @param msg Error message to show in the lower body of the error window + */ public void showError(String msg) { Alert alert = new Alert(Alert.AlertType.ERROR); alert.setHeaderText("Error"); diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/NewStationTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/NewStationTabController.java index b945304..eae4e16 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/NewStationTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/NewStationTabController.java @@ -6,6 +6,12 @@ import javafx.scene.control.Label; import javafx.scene.control.RadioButton; import javafx.scene.control.TextField; +/** + * Controller class for the "NewStation" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class NewStationTabController { @FXML @@ -18,26 +24,45 @@ public class NewStationTabController { private FuelStationUIController parentController; - // Called by parent after full initialization + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parent) { this.parentController = parent; } + /** + * Change the label text for the attribute + */ @FXML private void setAttributeTypeFromSmallStation() { attrLabel.setText("Number of drink vending machines:"); } + /** + * Change the label text for the attribute + */ @FXML private void setAttributeTypeFromMediumStation() { attrLabel.setText("m² of retail space:"); } + /** + * Change the label text for the attribute + */ @FXML private void setAttributeTypeFromLargeStation() { attrLabel.setText("Company running the integrated supermarket:"); } + /** + * Add a new fuel station + */ @FXML private void add() { try { diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/OverviewTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/OverviewTabController.java index 1cde85e..3b5d55c 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/OverviewTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/OverviewTabController.java @@ -3,7 +3,6 @@ package de.diejungsvondertanke.tankstelle.controllers; import de.diejungsvondertanke.tankstelle.Fuel; import de.diejungsvondertanke.tankstelle.FuelStation; import de.diejungsvondertanke.tankstelle.Main; -import javafx.application.Platform; import javafx.beans.property.SimpleFloatProperty; import javafx.beans.property.SimpleIntegerProperty; import javafx.beans.property.SimpleStringProperty; @@ -14,6 +13,12 @@ import javafx.scene.Parent; import javafx.scene.control.TableColumn; import javafx.scene.control.TableView; +/** + * Controller class for the "Overview" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class OverviewTabController { @FXML @@ -34,11 +39,21 @@ public class OverviewTabController { private FuelStationUIController parentController; - // Called by parent after full initialization + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parent) { this.parentController = parent; } + /** + * initialize the table + */ @FXML public void initialize() { colStation.setCellValueFactory(data -> new SimpleStringProperty(data.getValue().getStation())); @@ -49,6 +64,9 @@ public class OverviewTabController { colPrice.setCellValueFactory(data -> new SimpleFloatProperty(data.getValue().getPrice()).asObject()); } + /** + * Refresh the table to sync with latest changes + */ @FXML public void refresh() { table.getItems().clear(); @@ -71,7 +89,7 @@ public class OverviewTabController { table.getItems().add( new FuelRow( parentController.getDisplayName(station), - station.getClass().getSimpleName(), + station.getSimpleName(), f.FUEL_TYPE.toString(), f.getStored_amount(), f.CAPACITY, @@ -83,6 +101,13 @@ public class OverviewTabController { // table.setItems(list); } + /** + * This is just a debugging function. Do not use in a production environment + * + * @param node A displayed {@link Node} (i. e. from one of the Tabs) to display + * a tree-like inner structure for + * @param depth max. recursion depth + */ public static void printNodeTree(Node node, int depth) { // Indentation String indent = " ".repeat(depth); @@ -99,6 +124,9 @@ public class OverviewTabController { } } + /** + * Glorified record class for the data rows from the table. + */ public class FuelRow { String station; @@ -108,54 +136,164 @@ public class OverviewTabController { int capacity; float price; + /** + * Getter function + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @return the fuel station DISPLAY NAME, NOT THE STATION OBJECT + */ public String getStation() { return station; } + /** + * Set the new display name for the fuel station. + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param station new display name + */ public void setStation(String station) { this.station = station; } + /** + * Getter function + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @return the fuel station type as a string + */ public String getType() { return type; } + /** + * set new fuel station type as a string + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param type the new fuel station type + */ public void setType(String type) { this.type = type; } + /** + * Getter function + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @return the fuel type + */ public String getFuel() { return fuel; } + /** + * Set new fuel type as a string + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param fuel new fuel type as a string + */ public void setFuel(String fuel) { this.fuel = fuel; } + /** + * Getter function + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @return the stored fuel amount + */ public double getAmount() { return amount; } + /** + * Set new stored amount + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param amount new stored amount + */ public void setAmount(double amount) { this.amount = amount; } + /** + * Getter function + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @return maximum fuel capacity + */ public int getCapacity() { return capacity; } + /** + * Set new maximum fuel capacity + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param capacity new maximum fuel capacity + */ public void setCapacity(int capacity) { this.capacity = capacity; } + /** + * Getter function + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @return fuel price per litre + */ public float getPrice() { return price; } + /** + * Set new price per litre + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param price new price per litre + */ public void setPrice(float price) { this.price = price; } + /** + * constructs new FuelRows. This is used as a datatype in the "Overview" Tabs + * table + * + * Note: THIS IS DISPLAY ONLY. CHANGES WILL NOT AFFECT THE + * REAL STATION OBJECTS + * + * @param station display name for the fuel station + * @param type display name for the station type/size + * @param fuel display name for the fuel type + * @param amount stored amount of fuel + * @param capacity maximum capacity + * @param price price per litre + */ public FuelRow(String station, String type, String fuel, double amount, int capacity, float price) { this.station = station; this.type = type; diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/PriceTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/PriceTabController.java index 4a4df4e..27462f2 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/PriceTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/PriceTabController.java @@ -6,6 +6,12 @@ import de.diejungsvondertanke.tankstelle.error.NoSuchFuelTypeError; import javafx.fxml.FXML; import javafx.scene.control.TextField; +/** + * Controller class for the "Price" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class PriceTabController { @FXML @@ -13,11 +19,21 @@ public class PriceTabController { private FuelStationUIController parentController; - // Called by parent after full initialization + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parent) { this.parentController = parent; } + /** + * Save the price change + */ @FXML private void save() { FuelStation station = parentController.getSelectedStation(); @@ -41,7 +57,7 @@ public class PriceTabController { } catch (NumberFormatException ex) { parentController.showError("Invalid number."); } catch (NoSuchFuelTypeError ex) { - parentController.showError("Fuel type unavailable."); + parentController.showError("Fuel type not selected or unavailable."); } } } diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/ResultTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/ResultTabController.java index 58166cc..d9c9ecb 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/ResultTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/ResultTabController.java @@ -8,6 +8,12 @@ import javafx.fxml.FXML; import javafx.scene.control.ListView; import javafx.scene.control.SelectionMode; +/** + * Controller class for the "Result" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class ResultTabController { @FXML @@ -19,6 +25,14 @@ public class ResultTabController { listFuelStations.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE); } + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parentController) { this.parentController = parentController; } @@ -29,7 +43,9 @@ public class ResultTabController { } } - // Example action using parent + /** + * Output the total revenue if all fuel was sold at the set prices + */ @FXML private void handleTotalPrice() { if (parentController != null) { @@ -38,6 +54,9 @@ public class ResultTabController { } } + /** + * Output the fuel station with the highest price for a fuel type + */ @FXML private void handleHighestPrice() { FuelType type = parentController.comboFuelTypes.getValue(); @@ -50,6 +69,9 @@ public class ResultTabController { } } + /** + * Output the fuel station with the lowest price for a fuel type + */ @FXML private void handleHighestTotalValue() { try { @@ -60,6 +82,9 @@ public class ResultTabController { } } + /** + * + */ @FXML private void handleStock() { FuelType type = parentController.comboFuelTypes.getValue(); diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/SearchTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/SearchTabController.java index 0feddfb..1a9d121 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/SearchTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/SearchTabController.java @@ -6,11 +6,24 @@ import de.diejungsvondertanke.tankstelle.Main; import de.diejungsvondertanke.tankstelle.error.NoSuchFuelTypeError; import javafx.fxml.FXML; +/** + * Controller class for the "Search" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class SearchTabController { private FuelStationUIController parentController; - // Called by parent after full initialization + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parent) { this.parentController = parent; } diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/StockTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/StockTabController.java index 478ef44..778d6cd 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/StockTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/StockTabController.java @@ -8,6 +8,12 @@ import javafx.fxml.FXML; import javafx.scene.control.RadioButton; import javafx.scene.control.TextField; +/** + * Controller class for the "Stock" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class StockTabController { @FXML @@ -19,7 +25,14 @@ public class StockTabController { private FuelStationUIController parentController; - // Called by parent after full initialization + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parent) { this.parentController = parent; } @@ -32,6 +45,9 @@ public class StockTabController { throw new NoSuchFuelTypeError("Fuel type not available"); } + /** + * Save stock changes to the selected fuel type for the selected station + */ @FXML private void save() { FuelStation station = parentController.getSelectedStation(); diff --git a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/UnderstaffedTabController.java b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/UnderstaffedTabController.java index 9c0be25..55e4a01 100644 --- a/src/main/java/de/diejungsvondertanke/tankstelle/controllers/UnderstaffedTabController.java +++ b/src/main/java/de/diejungsvondertanke/tankstelle/controllers/UnderstaffedTabController.java @@ -7,6 +7,12 @@ import de.diejungsvondertanke.tankstelle.Main; import javafx.fxml.FXML; import javafx.scene.control.TextField; +/** + * Controller class for the "Understaffed" Tab + * + * @author Sergej Pavlenko + * @author Robin Cheney + */ public class UnderstaffedTabController { @FXML @@ -14,7 +20,14 @@ public class UnderstaffedTabController { private FuelStationUIController parentController; - // Called by parent after full initialization + /** + * For timing reasons this is a common method for every controller that is for a + * tab (not to confuse with the main window controller + * {@link FuelStationUIController}). This passes the controller object from the + * main controller to the controllers for the individual tabs as fields. + * Necessary, if you need to access any methods from the main controller, which + * is much likely the case + */ public void setParentController(FuelStationUIController parent) { this.parentController = parent; } -- 2.43.0