Interface GuiIfc

All Known Implementing Classes:
MainGui

public interface GuiIfc
This provides a GUI subsystem independent interface to the UI, so the backend can request GUI services without having to worry about whether it is AWT/Swing or something else (such as Android).

Note that any implementer of this interface is also required to:

  1. provide a no-argument constructor, and
  2. provide a static method with the signature: public static Object showSplashScreen() which creates a start-up splash screen and returns a handle to it so it can be taken down later with a static disposeOfSplash(Object) method.
Author:
Andrew Pavlin, KA2DDO
  • Method Details

    • setMainFrameTitle

      void setMainFrameTitle()
      Specify the title displayed in the main window's title bar.
    • initMainWindowMenuBar

      void initMainWindowMenuBar()
      Phase 2 of initializing the GUI (stuff that needs the GUI property of the main YAAC object to be already initialized).
    • getMainMap

      GeoMapIfc getMainMap()
      Get the primary or default map display.
      Returns:
      display object implementing the GeoMapIfc interface
    • iterateOverAllMaps

      void iterateOverAllMaps(GuiIfc.MapFunctor functor)
      Apply the functor to every currently open map window.
      Parameters:
      functor - MapFunctor to be iteratively called
    • iterateOverAllMaps

      void iterateOverAllMaps(GuiIfc.FullMapFunctor functor)
      Apply the functor to every currently open full-capability map window.
      Parameters:
      functor - FullMapFunctor to be iteratively called
    • getMessageCount

      int getMessageCount()
      Get the number of APRS Messages collected by the application.
      Returns:
      message count
    • invokeConfigWizard

      void invokeConfigWizard()
      Start the configuration wizard at its first window.
    • showConfigurationDialog

      void showConfigurationDialog()
      Start the regular configuration dialog.
    • createProgressReporter

      StatusListener createProgressReporter(String title, boolean modal)
      Open whatever the local operating system uses for a progress dialog and return an interface to send progress information to the dialog.
      Parameters:
      title - already-localized title String for the dialog
      modal - whether the dialog should be application-modal or modeless
      Returns:
      StatusListener to use for sending progress reports to the dialog
    • initializeWindowMenu

      void initializeWindowMenu(Object item, Object view)
      Create the entries on the dynamic Window menu on the menu bar corresponding to every window except the one containing the menu bar.
      Parameters:
      item - Object corresponding to the Window menu
      view - GUI window object containing the menu bar
    • showGenericErrorDialog

      void showGenericErrorDialog(String titleTag, String msg)
      Show a generic error message dialog, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
    • showGenericErrorDialogAlreadyLocalized

      void showGenericErrorDialogAlreadyLocalized(String title, String msg)
      Show a generic error message dialog, with the specified title and message text.
      Parameters:
      title - String dialog title
      msg - already-localized and variable-substituted error message text String
    • showGenericInfoDialog

      void showGenericInfoDialog(String titleTag, String msg)
      Show a generic informational message dialog, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
    • showGenericQuestionDialog

      int showGenericQuestionDialog(String titleTag, String msg)
      Show a generic yes/no question dialog, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
      Returns:
      0 for Yes, 1 for No, -1 for dialog closed without an explicit answer
    • showGenericQuestionDialogWithHelp

      int showGenericQuestionDialogWithHelp(String titleTag, String msg)
      Show a generic yes/no question dialog, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
      Returns:
      0 for Yes, 1 for No, 2 for Help, -1 for dialog closed without an explicit answer
    • showGenericInputDialog

      String showGenericInputDialog(String titleTag, String msg)
      Show a generic text input dialog, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted prompt message text String
      Returns:
      String text entered by user, or null to indicate dialog was closed without text entry
    • showCallsignInputDialog

      String showCallsignInputDialog(String titleTag, String msg)
      Show a text input dialog, with the specified title and message text, that will only take a callsign-SSID value for input.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted prompt message text String
      Returns:
      String text entered by user, or null to indicate dialog was closed without text entry
    • showCallsignInputDialog

      String showCallsignInputDialog(String titleTag, String msg, String oldValue)
      Show a text input dialog, with the specified title and message text, that will only take a callsign-SSID value for input.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted prompt message text String
      oldValue - String previous value, or null to leave blank
      Returns:
      String text entered by user, or null to indicate dialog was closed without text entry
    • showGenericPasswordDialog

      String showGenericPasswordDialog(String titleTag, String msg)
      Show a generic text input dialog, with the specified title and message text, where the entered text is masked (as should be done when entering a password).
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted prompt message text String
      Returns:
      String text entered by user, or null to indicate dialog was closed without text entry
    • showGenericStringChoiceDialog

      String showGenericStringChoiceDialog(String titleTag, String msg, String[] choices)
      Show a generic choice-box dialog pre-populated with the specified strings, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
      choices - String array of choices to populate the dropdown, or null for a text field
      Returns:
      String text entered by user or selected from choices, or null to indicate dialog was closed without text entry/selection
    • showGenericStringChoiceDialog

      String showGenericStringChoiceDialog(String titleTag, String msg, String[] choices, String initialChoice)
      Show a generic choice-box dialog pre-populated with the specified strings, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
      choices - String array of choices to populate the dropdown, or null for a text field
      initialChoice - String to ind
      Returns:
      String text entered by user or selected from choices, or null to indicate dialog was closed without text entry/selection
    • showGenericConfirmDialog

      int showGenericConfirmDialog(String titleTag, String msg)
      Show a generic retry/skip/cancel dialog, with the specified title and message text.
      Parameters:
      titleTag - String tag to look up locale-specific dialog title
      msg - already-localized and variable-substituted error message text String
      Returns:
      0 for Retry, 1 for Skip, 2 for Cancel, -1 for dialog closed without an explicit answer
    • setNightMode

      void setNightMode(boolean isNight)
      Specify that the displays should be in night mode (black backgrounds with white text/lines, for not ruining the night vision of the operator).
      Parameters:
      isNight - boolean true if should be in night mode
    • isNightMode

      boolean isNightMode()
      Report if the displays are in night mode.
      Returns:
      boolean true if in night mode
    • showAboutDialog

      void showAboutDialog()
      Display the About dialog for the YAAC application.
    • showReleaseNotes

      void showReleaseNotes()
      Display the release notes history for the YAAC application.
    • ensureKeystoreIsOpen

      boolean ensureKeystoreIsOpen(boolean dontBlock)
      Test if keystore has been opened with the correct password. If it hasn't, prompt the user for the password so the keystore can be opened,
      Parameters:
      dontBlock - boolean true if this method should return immediately without blocking
      Returns:
      boolean true if the keystore is now open
    • selectStation

      Object selectStation(String titleBarTag, boolean stationsOnly, boolean includeTacticalAliases)
      Select one station (or object, if allowed) from the currently known list, or allow the user to manually type in a station callsign-SSID, and return the user selected value.
      Parameters:
      titleBarTag - String tag for localized title to display in popup dialog
      stationsOnly - boolean true if entries appearing only as Objects/Items should be excluded from the pick list
      includeTacticalAliases - boolean true if tactical aliases of stations and objects should be included in the selection list
      Returns:
      String if user manually entered, StationState or String if selected from the pick list, or null if user cancelled the operation
    • selectOneOf

      int selectOneOf(String title, String[] choices)
      Create a popup dialog to ask the user which of several choices should be used.
      Parameters:
      title - String title to display in dialog box title
      choices - array of String choices to choose from
      Returns:
      index of selected choice, or -1 if the dialog was cancelled without selecting a choice
    • loadAprsPackets

      void loadAprsPackets()
      Query the user for a file from which to load saved APRS messages.
    • saveAprsPackets

      void saveAprsPackets()
      Query the user for a file in which to save the current visible set of APRS messages.
    • getSaveableTableInView

      SaveableTable getSaveableTableInView(Object view)
      Get the SaveableTable (if any) in the specified view.
      Parameters:
      view - top-level window or view to be tested
      Returns:
      SaveableTable object in the view, or null if there isn't a SaveableTable in the view
    • showMap

      void showMap()
      Make visible and foreground the map window.
    • displayOsmMirrorSiteList

      void displayOsmMirrorSiteList()
      Display a popup with buttons to launch the user's web browser pointed at any of the major download sites for raw OpenStreetMap data.
    • displayOsmImportDialog

      GuiIfc.OsmImportParams displayOsmImportDialog(File osmFileDir)
      Ask the user how and where from to import an OpenStreetMap compressed data file.
      Parameters:
      osmFileDir - File pointing at the directory to initially look for importable OSM data files
      Returns:
      null if user cancelled the request, or an OsmImportParams object containing the import parameters
    • displayOsmTileDownloadDialog

      GuiIfc.TileDownloadParams displayOsmTileDownloadDialog(ChangeSet localChangeSet, ChangeSet serverChangeSet)
      Display a dialog asking the user which pre-compiled OSM tiles to download.
      Parameters:
      localChangeSet - the OSM ChangeSet of the last data downloaded or imported here (or null if OSM data was never installed)
      serverChangeSet - the OSM ChangeSet currently available on the YAAC website
      Returns:
      null if the user cancelled the request, or a TileDownloadParams structure containing the needed parameters for the download
    • displayTopoTileDownloadDialog

      GuiIfc.TileDownloadParams displayTopoTileDownloadDialog(File tileDir)
      Display a dialog asking the user which SRTM tiles to download.
      Parameters:
      tileDir - File pointing at the directory where tiles are kept
      Returns:
      null if the user cancelled the request, or a TileDownloadParams structure containing the needed parameters for the download
    • selectFileForWrite

      File selectFileForWrite(File dir, String fileExtensionTag, String fileExtension)
      Open a file selection dialog for saving a file.
      Parameters:
      dir - File for the initial directory
      fileExtensionTag - String tag for looking up localized string of file type description
      fileExtension - String file type
      Returns:
      selected File to save the content to, or null if cancelled
    • selectFile

      String selectFile(boolean isDirectory, String promptTag, String fileSelectTag)
      Select a file using an O/S-provided file chooser.
      Parameters:
      isDirectory - boolean true if user should select a directory, false to select a file
      promptTag - String key to ResourceBundle localized dialog title
      fileSelectTag - String key to ResourceBundle localized select button label
      Returns:
      String of selected file path, or null if not selected
    • importConfigFromFile

      void importConfigFromFile()
      Import a configuration from a saved XML file (File->Configure->Export to File) with appropriate interferences for callsign, directory, and serial port changing.
    • analyzeConfiguration

      void analyzeConfiguration()
      Analyze the current configuration to report what the station as a whole will do. Intended to catch unreasonable configurations that don't do what the user wants it to do.
    • showRawPacketFrame

      void showRawPacketFrame()
      Display the raw packet window.
    • showMessageFrame

      void showMessageFrame()
      Open the MessageFrame (window displaying text message traffic in a table) and move it to the foreground. This may be called from any thread (not just the GUI dispatch thread).
    • showMessageFilterPane

      void showMessageFilterPane()
      Display the window used for receiving and logging filtered text messages. Intended to support proposed field event logging as described in http://aprs.org/aprsevent.html
    • showBulletinBoard

      void showBulletinBoard()
      Display the window used to display bulletin messages, and compose locally originated bulletins for transmission.
    • showOutstandingMessages

      void showOutstandingMessages()
      Display the window showing all messages (except beacons and status messages) pending for transmission from the local station.
    • showBandwidthMonitor

      void showBandwidthMonitor()
      Display a bandwidth monitor for each open I/O port in YAAC.
    • showGpsStatusDialog

      void showGpsStatusDialog()
      Display a monitor of the current status of all GPS receivers connected to YAAC.
    • showWeatherDialog

      void showWeatherDialog()
      Display a monitor of the current conditions reported by the local weather station attached to YAAC.
    • showHeardList

      void showHeardList()
      Display a report of number of packets received from each station (or about each APRS Object/Item) over 15 minute intervals in the YAAC history.
    • showConnectionReport

      void showConnectionReport()
      Display outstanding connected (I-frame) AX.25 sessions.
    • showRadioView

      void showRadioView(Message msg, String identifier)
      Show the dialog that looks like the Kenwood D710 control head APRS display.
      Parameters:
      msg - a historical APRS Message to display, or null to display current real-time data
      identifier - the originating station callsign associated with the historical message (ignored if null msg)
    • showStationList

      void showStationList()
      Show the window listing all the stations and objects heard by this station.
    • showLocalObjects

      void showLocalObjects()
      Display a table of all Objects/Items being transmitted by this station.
    • showHistory

      void showHistory(StationState ss)
      Display the message history for a specified station or object.
      Parameters:
      ss - StationState of the desired station or object
    • showTelemetryReport

      void showTelemetryReport()
      Display all the current telemetry data heard by this station.
    • showHealthMonitorReport

      void showHealthMonitorReport()
      Show the current station health reports for all remote stations being monitored.
    • showTXIGatedStations

      void showTXIGatedStations()
      Show a table view of the stations currently being Tx I-gated by this station.
    • showKeys

      void showKeys()
      Show a table view of the keys used to authenticate and verify the integrity of signed messages.
    • showDXReports

      void showDXReports()
      Show a table view of all DX reports received by this station.
    • showEditFilterDialog

      void showEditFilterDialog(Filter mainFilter, String dialogTitleTag)
      Generate and display the filter dialog.
      Parameters:
      mainFilter - the top Filter in the Filter hierarchy
      dialogTitleTag - bundle tag for title to display on dialog
    • showEditBlacklistDialog

      void showEditBlacklistDialog()
      Generate and display the blacklist editor.
    • loadObjectsFromFile

      void loadObjectsFromFile()
      Load APRS Object definitions from a user-specified file.
    • saveObjectsToFile

      void saveObjectsToFile()
      Save the currently known APRS Objects to a file.
    • loadTacticalNames

      void loadTacticalNames()
      Load alias names and symbol codes for station callsigns and object names.
    • saveTacticalNames

      void saveTacticalNames()
      Save alias names and symbol codes for station callsigns and object names.
    • displayAttentionAlert

      void displayAttentionAlert(StationState ss)
      Display an AttentionAlert (flashing arrows) on the map for a particular station or object.
      Parameters:
      ss - StationState of the station or object to highlight
    • displayAttentionAlert

      void displayAttentionAlert(double latitude, double longitude, AX25Message.Precedence precedence)
      Display an AttentionAlert (flashing arrows) on the map for a particular station or object.
      Parameters:
      latitude - double fractional degrees North
      longitude - double fraction degrees East
      precedence - Precedence of the event to be reported
    • displayLocateLandmarkDialog

      void displayLocateLandmarkDialog()
      Display the Locate Landmark dialog, and handle user input to it.
    • displayStationSpecificMap

      void displayStationSpecificMap(StationState station)
      Open a map window centered on the station or object specified.
      Parameters:
      station - StationState to center on
    • composeWinlinkMessage

      void composeWinlinkMessage()
      Display a form to allow transmitting a multi-line email message to someone via the APRS-WinLink gateways.
    • connectToStation

      void connectToStation()
      Set up a dumb-terminal connection to an old-style packet BBS.
    • confirmSendBroadcastQuery

      void confirmSendBroadcastQuery(String confirmTag, String query)
      Broadcast a specified global query message after confirming the user really wants to send it.
      Parameters:
      confirmTag - tag for resource file message for the confirmation query
      query - the actual APRS message to send (must be valid according to the APRS protocol specification)
    • approveTacticalSender

      void approveTacticalSender(String originatingCallsign, String tacticalMsgText)
      Queue up a request to ask the user whether this TACTICAL message should be accepted and processed. This is expected to be called from a background thread, so the implementor is required to move it to the GUI dispatch thread.
      Parameters:
      originatingCallsign - callsign String of message originator
      tacticalMsgText - String of text message body (the TACTICAL directive)
    • sendQRU

      void sendQRU()
      Broadcast a specified QRU query message after confirming the user really wants to send it. and asking which QRU category to ask for.
    • invokeObjectEditor

      void invokeObjectEditor(String dialogTitleTag, Message or, int mouseX, int mouseY, ObjectReportTransmitter tx)
      Display the Object editing dialog, possibly initialized with the contents of an existing ObjectReport.
      Parameters:
      dialogTitleTag - String tag for localized title to display on dialog title bar
      or - APRS Message to initialize the editor, or null for creating an object from scratch
      mouseX - window X coordinate of mouse click (to generate initial coordinates), or -1 to not init position from map
      mouseY - window Y coordinate of mouse click (to generate initial coordinates), or -1 to not init position from map
      tx - ObjectReportTransmitter to give any created or updated objects to
    • invokeObjectEditor

      void invokeObjectEditor(String dialogTitleTag, Message or, int mouseX, int mouseY, ObjectReportTransmitter tx, Scope scope)
      Display the Object editing dialog, possibly initialized with the contents of an existing ObjectReport.
      Parameters:
      dialogTitleTag - String tag for localized title to display on dialog title bar
      or - APRS Message to initialize the editor, or null for creating an object from scratch
      mouseX - window X coordinate of mouse click (to generate initial coordinates), or -1 to not init position from map
      mouseY - window Y coordinate of mouse click (to generate initial coordinates), or -1 to not init position from map
      tx - ObjectReportTransmitter to give any created or updated objects to
      scope - Scope for new ObjectReport (ignored for existing ObjectReports), or null for default
    • showIOFailureDialog

      void showIOFailureDialog(PortConfig config, String reason, PortFailureReportListener listener)
      Display an asynchronous non-blocking dialog on the screen to report an I/O error. This method should only be called from background threads (such as port I/O handling threads), and not from the AWT dispatch thread.
      Parameters:
      config - PortConfig object describing the port with the problem, or null if not about a specific port
      reason - String describing why the port is down
      listener - I/O subsystem that wants to be informed if the user dismisses the dialog
    • closeCurrentWindow

      void closeCurrentWindow()
      Close the window that currently has the keyboard focus (if it is part of the YAAC application).
    • pickAStation

      StationState pickAStation(List<StationState> matchList, String titleTag)
      Select one of several stations.
      Parameters:
      matchList - java.util.List of StationState objects to pick from
      titleTag - String name of resource tag for title of prompting dialog
      Returns:
      selected StationState, or null if the user cancelled
    • pickObject

      Object pickObject(String titleTag, List<Object> matchList)
      Select one of several objects. The toString() method of each object in the specified list must return the name that should be displayed in the list for the object.
      Parameters:
      titleTag - String name of resource tag for title of prompting dialog
      matchList - java.util.List of objects to pick from
      Returns:
      selected StationState, or null if the user cancelled
    • scheduleToGuiThread

      void scheduleToGuiThread(Runnable r)
      Schedule a short-running operation that should only occur on the GUI dispatch thread (however the implementing GUI chooses to do it).
      Parameters:
      r - Runnable to be scheduled as soon as possible on the GUI thread
    • getCurrentlyFocusedView

      Object getCurrentlyFocusedView()
      Get the UI platform top-level widget that currently holds the focus.
      Returns:
      top-level GUI object
    • getCurrentTopLevelView

      Object getCurrentTopLevelView()
      Get the UI platform top-level widget that currently holds the focus, skipping child dialogs.
      Returns:
      top-level GUI object
    • editStationNotes

      void editStationNotes(StationState station, int mouseX, int mouseY)
      Display and edit notes attached to a specific station or object.
      Parameters:
      station - StationState whose notes should be edited
      mouseX - window X coordinate of mouse click (to generate initial coordinates), or -1 to not init position from map
      mouseY - window Y coordinate of mouse click (to generate initial coordinates), or -1 to not init position from map
    • setStationTimeout

      void setStationTimeout(StationState station)
      Edit the timeout value for the specified station.
      Parameters:
      station - StationState whose inactivity time limit is to be modified
    • showTrackedStationsList

      void showTrackedStationsList()
      Display a dialog for viewing and modifying the list of specifically tracked stations.
    • isViewPrintable

      boolean isViewPrintable(Object o, int depthLeft)
      Test if specified GUI view is printable.
      Parameters:
      o - Object of view container
      depthLeft - number of levels of recursion allowed for the search
      Returns:
      boolean true if view is printable
      See Also:
    • printWindow

      void printWindow()
      Print the window that currently has the focus.
      See Also:
    • setMemoryGCPanelVisible

      void setMemoryGCPanelVisible(boolean visible)
      Change the visibility of the memory usage status monitor for all map windows.
      Parameters:
      visible - boolean true if memory status monitor should be visible
    • isMemoryGCPanelVisible

      boolean isMemoryGCPanelVisible()
      Report the current visibility of the MemoryGCPanel.
      Returns:
      boolean true if panel is visible
    • displayHeardByDialog

      Object[] displayHeardByDialog(StationState[] stationsToPickFrom)
      Display a dialog asking for the parameters for a Heard-By (?APRSH) query.
      Parameters:
      stationsToPickFrom - array of StationState objects specifying the list of stations to choose from, or null to get all currently known stations
      Returns:
      null if the query was cancelled, or a two-element array specifying the station to query and the station that the queried station might have heard
    • displayMessagingDialog

      GuiIfc.MessagingParams displayMessagingDialog(ArrayList ssList)
      Display a dialog asking the user for the parameters needed to send a text message to another station.
      Parameters:
      ssList - list of stations to populate the list with, or null for entire list of known stations
      Returns:
      null if the user cancelled the request, or a MessagingParams structure containing the parameters
    • startChatSession

      void startChatSession(String callsign)
      Open a Chat session window pointed at the specified remote station.
      Parameters:
      callsign - String callsign of the remote station
    • displayHelp

      void displayHelp(String startingHelpId, Object parentWindow)
      Launch the JavaHelp browser, starting with the help corresponding to the specified help ID
      Parameters:
      startingHelpId - String help ID corresponding to an entry in a *.jhm file; null indicates the top of the TOC view, empty string indicates the top of the Index view
      parentWindow - window to parent an incarnation of the HelpBroker
    • checkForUpdates

      void checkForUpdates(boolean interactive)
      Check whether a newer release of YAAC is available, displaying status.
      Parameters:
      interactive - boolean true if no-upgrade-needed status should be reported (out-of-date status is always reported)
    • showPluginStore

      void showPluginStore()
      Display a dialog for selecting new officially supported plugins to install.
    • clearAllSpecificTrackStripes

      void clearAllSpecificTrackStripes()
      Clear the plotting of all specific station/object track stripes.
    • addSpecificTrackStripe

      void addSpecificTrackStripe(String identifier)
      Add the identifier of a single station or object whose track stripe is to be plotted.
      Parameters:
      identifier - String station or object identifier
    • removeSpecificTrackStripe

      boolean removeSpecificTrackStripe(String identifier)
      Remove the identifier of a single station or object whose track stripe is no longer to be plotted.
      Parameters:
      identifier - String station or object identifier
      Returns:
      boolean true if identifier was removed
    • isSpecificallyTracked

      boolean isSpecificallyTracked(String identifier)
      Test if a given identifier is on the tracking list.
      Parameters:
      identifier - String station or object identifier
      Returns:
      boolean true if this identifier is marked for track stripe display
    • isSpecificallyTracking

      boolean isSpecificallyTracking()
      Test if any identifiers are on the tracking list.
      Returns:
      boolean true if any stations are specifically tagged for tracking
    • getSpeechCustomGrammarForCurrentView

      SpeechMapGeneratorIfc getSpeechCustomGrammarForCurrentView()
      Ask the current window whether it has any overriding grammar for speech command. If it does, an object that will generate a map of speakable command strings (with certain macros) to the corresponding handlers should be returned. If the window does not have any overrides, the speech command plugin will continue to use the default grammar.

      For example, one command string for the message sender dialog could be:

      to <callsign> via <alias>
      Returns:
      SpeechMapGeneratorIfc implementation, or null if no customization