/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2014 Raritan Inc. All rights reserved.
 */

#include <UserEvent.idl>

/** Front panel display interface */
module display {
    /**
     * Interface to control the device's front panel display
     */
    interface DisplayControl_2_0_0 {
        /**
         * Error codes
         */
        constant int SUCCESS           = 0; ///< No error
        constant int ERR_INVALID_VALUE = 1; ///< Invalid argument

        /** Collected display meta information */
        structure Info {
            int fwAppVersion;           ///< Firmware application version; 0 if unavailable
            int fwBootVersion;          ///< Firmware bootloader version; 0 if unavailable
            int orientation;            ///< Display orientation
            int width;                  ///< Display width
            int height;                 ///< Display height
            boolean versionAvailable;   ///< \c true if version information is available
        };

        /**
         * Representation of a possible default view
         */
        structure DefaultViewItem {
            string id;                  ///< View ID
            string description;         ///< Textual description
        };

        structure Settings {
            string defaultView;         ///< Default view ID (might be an empty string
                                        ///< if the device doesn't allow default view configuration)
            int backlightTimeout;       ///< Backlight timeout in seconds, or 0 for no timeout
        };

        /** Event: Settings were changed */
        valueobject SettingsChangedEvent extends event.UserEvent {
            Settings newSettings;       ///< New settings
        };

        /**
         * Get available default views. This returns all views that can be
         * used as default views on the device display.
         *
         * @return Possible default views, or empty list if the default view
         *         can not be configured for the device's display
         */
        vector<DefaultViewItem> getAvailableDefaultViews();

        /**
         * Get the current settings
         *
         * @return settings
         */
        Settings getSettings();

        /**
         * Update the settings
         *
         * @param settings Settings to be applied
         *
         * @return 0 on success
         * @return 1 on invalid value
         */
        int setSettings(in Settings settings);

        /**
         * Retrieve display's meta information.
         *
         * @return Display information
         */
        Info getInfo();

        /**
         * Show smiley on display
         *
         * @param on    \c true to turn on smiley
         * @param happy \c true to show happy smiley,\c false to show sad smiley
         * @param msg   String for message
         */
        void showSmiley(in boolean on, in boolean happy, in string msg);
    };
}
