Add fluent builders for more flexibly adding data to Shuffleboard (#1022)

2026-07-06 03:31:43 +00:00 · 2018-09-28 04:18:18 -04:00
parent ac7dfa5042
commit 175c6c1f01
51 changed files with 3120 additions and 0 deletions
--- a/wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h
+++ b/wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h
@@ -0,0 +1,111 @@
+/*----------------------------------------------------------------------------*/
+/* Copyright (c) 2018 FIRST. All Rights Reserved.                             */
+/* Open Source Software - may be modified and shared by FRC teams. The code   */
+/* must be accompanied by the FIRST BSD license file in the root directory of */
+/* the project.                                                               */
+/*----------------------------------------------------------------------------*/
+
+#pragma once
+
+#include <wpi/StringRef.h>
+
+#include "frc/shuffleboard/ShuffleboardInstance.h"
+
+namespace frc {
+
+class ShuffleboardTab;
+
+/**
+ * The Shuffleboard class provides a mechanism with which data can be added and
+ * laid out in the Shuffleboard dashboard application from a robot program. Tabs
+ * and layouts can be specified, as well as choosing which widgets to display
+ * with and setting properties of these widgets; for example, programmers can
+ * specify a specific {@code boolean} value to be displayed with a toggle button
+ * instead of the default colored box, or set custom colors for that box.
+ *
+ * For example, displaying a boolean entry with a toggle button:
+ * <pre>{@code
+ * NetworkTableEntry myBoolean = Shuffleboard.getTab("Example Tab")
+ *   .add("My Boolean", false)
+ *   .withWidget("Toggle Button")
+ *   .getEntry();
+ * }</pre>
+ *
+ * Changing the colors of the boolean box:
+ * <pre>{@code
+ * NetworkTableEntry myBoolean = Shuffleboard.getTab("Example Tab")
+ *   .add("My Boolean", false)
+ *   .withWidget("Boolean Box")
+ *   .withProperties(Map.of("colorWhenTrue", "green", "colorWhenFalse",
+ * "maroon")) .getEntry();
+ * }</pre>
+ *
+ * Specifying a parent layout. Note that the layout type must <i>always</i> be
+ * specified, even if the layout has already been generated by a previously
+ * defined entry.
+ * <pre>{@code
+ * NetworkTableEntry myBoolean = Shuffleboard.getTab("Example Tab")
+ *   .getLayout("List", "Example List")
+ *   .add("My Boolean", false)
+ *   .withWidget("Toggle Button")
+ *   .getEntry();
+ * }</pre>
+ * </p>
+ *
+ * Teams are encouraged to set up shuffleboard layouts at the start of the robot
+ * program.
+ */
+class Shuffleboard final {
+ public:
+  /**
+   * The name of the base NetworkTable into which all Shuffleboard data will be
+   * added.
+   */
+  static constexpr const char* kBaseTableName = "/Shuffleboard";
+
+  /**
+   * Updates all the values in Shuffleboard. Iterative and timed robots are
+   * pre-configured to call this method in the main robot loop; teams using
+   * custom robot base classes, or subclass SampleRobot, should make sure to
+   * call this repeatedly to keep data on the dashboard up to date.
+   */
+  static void Update();
+
+  /**
+   * Gets the Shuffleboard tab with the given title, creating it if it does not
+   * already exist.
+   *
+   * @param title the title of the tab
+   * @return the tab with the given title
+   */
+  static ShuffleboardTab& GetTab(wpi::StringRef title);
+
+  /**
+   * Enables user control of widgets containing actuators: speed controllers,
+   * relays, etc. This should only be used when the robot is in test mode.
+   * IterativeRobotBase and SampleRobot are both configured to call this method
+   * when entering test mode; most users should not need to use this method
+   * directly.
+   */
+  static void EnableActuatorWidgets();
+
+  /**
+   * Disables user control of widgets containing actuators. For safety reasons,
+   * actuators should only be controlled while in test mode. IterativeRobotBase
+   * and SampleRobot are both configured to call this method when exiting in
+   * test mode; most users should not need to use this method directly.
+   */
+  static void DisableActuatorWidgets();
+
+ private:
+  static detail::ShuffleboardInstance& GetInstance();
+
+  // TODO usage reporting
+
+  Shuffleboard() = default;
+};
+
+}  // namespace frc
+
+// Make use of references returned by member functions usable
+#include "frc/shuffleboard/ShuffleboardTab.h"