// zlib open source license // // Copyright (c) 2018 to 2023 David Forsgren Piuva // // This software is provided 'as-is', without any express or implied // warranty. In no event will the authors be held liable for any damages // arising from the use of this software. // // Permission is granted to anyone to use this software for any purpose, // including commercial applications, and to alter it and redistribute it // freely, subject to the following restrictions: // // 1. The origin of this software must not be misrepresented; you must not // claim that you wrote the original software. If you use this software // in a product, an acknowledgment in the product documentation would be // appreciated but is not required. // // 2. Altered source versions must be plainly marked as such, and must not be // misrepresented as being the original software. // // 3. This notice may not be removed or altered from any source // distribution. #ifndef DFPSR_GUI_VISUALTHEME #define DFPSR_GUI_VISUALTHEME #include "../../api/mediaMachineAPI.h" #include "componentStates.h" namespace dsr { // ---------------------------------------- WARNING! ---------------------------------------- // // This API is not yet finished and may break backwards compatibility before completed. // It is not yet decided if the media machine will expose virtual assembly code, // which syntax to define themes using or if themes should be bundled together into archives. // // ------------------------------------------------------------------------------------------ // TODO: Move to the API folder once complete. // A handle to a GUI theme. // Themes describes the visual appearance of an interface. // By having more than one theme for your interface, you can let the user select one. class VisualThemeImpl; using VisualTheme = Handle; // Create a theme using a virtual machine with functions to call, style settings telling which functions to call with what arguments, and a path to load any non-embedded images from. VisualTheme theme_createFromText(const MediaMachine &machine, const ReadableString &styleSettings, const ReadableString &fromPath); // Create a theme using a virtual machine with functions to call, and a path to the style settings to load. // Any non-embedded images will be loaded relative to styleFilename's folder; VisualTheme theme_createFromFile(const MediaMachine &machine, const ReadableString &styleFilename); // Get a handle to the default theme. VisualTheme theme_getDefault(); // Returns true iff theme exists, otherwise false. bool theme_exists(const VisualTheme &theme); // Returns the index of className in theme, 0 if it did not exist in theme or -1 if theme does not exist. int theme_getClassIndex(const VisualTheme &theme, const ReadableString &className); // Returns true iff className exists in theme. bool theme_class_exists(const VisualTheme &theme, const ReadableString &className); // Returns suggestedClassName if it exists in theme, fallbackClassName otherwise. String theme_selectClass(const VisualTheme &theme, const ReadableString &suggestedClassName, const ReadableString &fallbackClassName); // Getters for resources in the theme's *.ini configuration file. // If className is not found in the theme, the settings declared before the first class are used. // This allow unhandled components to have a generic look, get a pattern that signals unfinished work or leave it blank to terminate with an error when a class is not handled. // Settings after the class name within [] until the end of the file or next class belong to that class. // Get the scalable image created using the media machine method name stored in the string setting "method" within className in theme. // If there is no method name assigned to "method" after [className], the "method" before the first [] block is used instead. // If no method is found at all, it means that the theme wants to throw an exception to alert the developer about a class that needs to be handled. // The matches for className and "method" are both case insensitive. MediaMethod theme_getScalableImage(const VisualTheme &theme, const ReadableString &className); // TODO: Create syntax for naming sub-image regions within the atlas to be used as icons without needing to load separate files. // Get a fixed size image from className in theme using settingName, an empty handle if not found in theme or theme does not exist. // Looks for image assignments to settingName after [className] first, then before the first [] block, and then returns an empty handle if not found at all. // The matches for className and settingName are both case insensitive. // Use theme_getClassIndex if you are unsure of why an empty handle was returned, because it will not throw exceptions. OrderedImageRgbaU8 theme_getImage(const VisualTheme &theme, const ReadableString &className, const ReadableString &settingName); // Get a fixed-point value from className in theme using settingName, the default value if not found, or throw an exception if theme does not exist. // Looks for scalar assignments to settingName after [className] first, then before the first [] block, and then returns defaultValue if not found at all. // The matches for className and settingName are both case insensitive. // Use theme_getClassIndex if you are unsure of why defaultValue was returned, because it will not throw exceptions. FixedPoint theme_getFixedPoint(const VisualTheme &theme, const ReadableString &className, const ReadableString &settingName, const FixedPoint &defaultValue); // Get FixedPoint and truncate to an integer, which should leave 16 bits of useful range. int theme_getInteger(const VisualTheme &theme, const ReadableString &className, const ReadableString &settingName, const int &defaultValue); // Get a string from className in theme using settingName, the default value if not found, or throw an exception if theme does not exist. // Looks for string assignments to settingName after [className] first, then before the first [] block, and then returns defaultValue if not found at all. // The matches for className and settingName are both case insensitive. // Use theme_getClassIndex if you are unsure of why defaultValue was returned, because it will not throw exceptions. ReadableString theme_getString(const VisualTheme &theme, const ReadableString &className, const ReadableString &settingName, const FixedPoint &defaultValue); // Called by VisualComponent to assign input arguments to functions in the media machine that were not given by the component itself. // Post-condition: Returns true if argumentName was identified and assigned as input to inputIndex of methodIndex in machine. bool theme_assignMediaMachineArguments(const VisualTheme &theme, int contextIndex, MediaMachine &machine, int methodIndex, int inputIndex, const ReadableString &argumentName); // Post-condition: // Returns a bit-mask for the direct states that have corresponding input arguments in the method. // Includes the componentState_focusDirect bit if the method has an input argument named "focused". // Includes the componentState_hoverDirect bit if the method has an input argument named "hover". ComponentState theme_getStateListenerMask(const MediaMethod &scalableImage); } #endif