MRUIStyle.h

Go to the documentation of this file.

#pragma once
 
#include "MRMesh/MRFinally.h"
#include "MRNotificationType.h"
#include "exports.h"
#include "MRUnits.h"
#include "MRVectorTraits.h"
#include "MRImGui.h"
#include <span>
#include <string>
#include <optional>
#include <filesystem>
 
namespace MR
{
 
class ImGuiImage;
 
namespace UI
{
 
// Returns the global UI scale. Use this instead of passing around the scale in parameters.
[[nodiscard]] MRVIEWER_API float scale();
 
namespace detail
{
    // Strictly for internal use. Updates the value that `scale()` returns.
    MRVIEWER_API void setScale( float newScale );
}
 
// Checks if the item with this name in the current window is active.
[[nodiscard]] MRVIEWER_API bool isItemActive( const char* name );
 
// Use this to store state across frames. Like what `CollapsingHeader()` uses to store it's open/close state.
namespace StateStorage
{
 
[[nodiscard]] MRVIEWER_API bool readBool( std::string_view key, bool defaultValue = false );
MRVIEWER_API void writeBool( std::string_view key, bool value );
 
}
 
// enumeration texture types
enum class TextureType
{
    Mono,
    Gradient,
    GradientBtn,
    GradientBtnSecond,
    GradientBtnGray,
    RainbowRect,
    Count
};
 
// get texture by type
MRVIEWER_API std::unique_ptr<ImGuiImage>& getTexture( TextureType type );
 
MRVIEWER_API void init();
 
struct ButtonCustomizationParams
{
    bool enabled = true;
 
    ImGuiButtonFlags flags = ImGuiButtonFlags_None;
 
    ImGuiImage* customTexture = nullptr;
 
    bool forceImGuiBackground = false;
 
    bool forceImguiTextColor = false;
    bool border = false;
 
    bool underlineFirstLetter = false;
 
    bool enableTestEngine = true;
 
    std::string testEngineName;
};
 
struct ButtonIconCustomizationParams
{
    // basic customization parameters
    ButtonCustomizationParams baseParams;
 
    // if false - text is to the right
    bool textUnderImage = true;
};
 
struct PlotAxis
{
    // the point from which the axes will be drawn
    ImVec2 startAxisPoint;
 
    // size plot by axis
    float size = 100.f;
    // optimal length between dashes
    float optimalLenth = 10.0f;
    // the minimum value of the axis
    float minValue = 0.0f;
    // the maximal value of the axis
    float maxValue = 1.0f;
    // sign every nth dash
    size_t textDashIndicesStep = 1;
 
    // length dash without text
    float lenDash = 8.0f;
    // length dash with text
    float lenDashWithText = 12.0f;
    // text offset from dash
    float textPadding = 3.0f;
    // the format of the text for labels
    VarUnitToStringParams labelFormatParams;
};
 
MRVIEWER_API ImGuiKey getImGuiModPrimaryCtrl();
 
MRVIEWER_API const char* getImGuiPrimaryCtrlName();
 
MRVIEWER_API bool checkKey( ImGuiKey passedKey );
 
[[deprecated( "Use UI::buttonEx( label, size, params ) instead" )]]
MRVIEWER_API bool buttonEx( const char* label,bool active, const Vector2f& size = Vector2f( 0, 0 ),
    ImGuiButtonFlags flags = ImGuiButtonFlags_None, const ButtonCustomizationParams& customParams = {} );
 
MRVIEWER_API bool buttonEx( const char* label, const Vector2f& size = Vector2f( 0, 0 ), const ButtonCustomizationParams& customParams = {} );
MRVIEWER_API bool button( const char* label, bool active, const Vector2f& size = Vector2f( 0, 0 ), ImGuiKey key = ImGuiKey_None );
inline bool button( const char* label, const Vector2f& size = Vector2f( 0, 0 ), ImGuiKey key = ImGuiKey_None )
{
    return button( label, true, size, key );
}
MRVIEWER_API bool buttonCommonSize( const char* label, const Vector2f& size = Vector2f( 0, 0 ), ImGuiKey key = ImGuiKey_None );
MRVIEWER_API bool buttonUnique( const char* label, int* value, int ownValue, const Vector2f& size = Vector2f( 0, 0 ), ImGuiKey key = ImGuiKey_None );
 
// draw dash with text along the horizontal axis
MRVIEWER_API void drawPoltHorizontalAxis( const PlotAxis& plotAxis );
// draw dash with text along the vertical axis
MRVIEWER_API void drawPoltVerticalAxis( const PlotAxis& plotAxis );
 
// draw a button with an icon and text under it
MRVIEWER_API bool buttonIconEx(
    const std::string& name,
    const Vector2f& iconSize,
    const std::string& text,
    const ImVec2& buttonSize,
    const ButtonIconCustomizationParams& params = {} );
 
// button with a gradient, always active
inline bool buttonIcon( const std::string& name, const Vector2f& iconSize, const std::string& text, const ImVec2& buttonSize )
{
    return buttonIconEx( name, iconSize, text, buttonSize );
}
// button without a gradient, always active, configurable by an external style
inline bool buttonIconFlatBG(
    const std::string& name,
    const Vector2f& iconSize,
    const std::string& text,
    const ImVec2& buttonSize,
    bool textUnderIcon = true,
    ImGuiKey key = ImGuiKey_None )
{
    ButtonIconCustomizationParams params;
    params.baseParams.forceImGuiBackground = true;
    params.baseParams.forceImguiTextColor = true;
    params.textUnderImage = textUnderIcon;
    params.baseParams.underlineFirstLetter = std::string_view( ImGui::GetKeyName( key ) ) == std::string_view( text.c_str(), 1 );
    return buttonIconEx( name, iconSize, text, buttonSize, params ) || checkKey( key );
}
MRVIEWER_API bool buttonUniqueIcon(
    const std::string& iconName,
    const Vector2f& iconSize,
    const std::string& text,
    const ImVec2& buttonSize,
    int* value,
    int ownValue,
    bool textUnderIcon = true,
    ImGuiKey key = ImGuiKey_None );
 
 
MRVIEWER_API bool toggle( const char* label, bool* value );
MRVIEWER_API bool checkbox( const char* label, bool* value );
MRVIEWER_API bool checkboxOrFixedValue( const char* label, bool* value, std::optional<bool> valueOverride );
MRVIEWER_API bool checkboxValid( const char* label, bool* value, bool valid );
MRVIEWER_API bool checkboxMixed( const char* label, bool* value, bool mixed );
template <typename Getter, typename Setter>
bool checkbox( const char* label, Getter get, Setter set )
{
    bool value = get();
    bool ret = checkbox( label, &value );
    set( value );
    return ret;
}
template <typename Getter, typename Setter>
bool checkboxValid( const char* label, Getter get, Setter set, bool valid )
{
    bool value = get();
    bool ret = checkboxValid( label, &value, valid );
    set( value );
    return ret;
}
 
template <typename T>
bool checkboxFlags( const char* label, T& target, T flags )
{
    bool value = bool( target & flags );
    bool mixed = value && ( target & flags ) != flags;
    if ( checkboxMixed( label, &value, mixed ) )
    {
        if ( value )
            target |= flags;
        else
            target &= ~flags;
        return true;
    }
    return false;
}
 
struct CheckboxOrModifierState
{
    // The persistent value of this setting, as set by the user by clicking the checkbox.
    bool baseValue = false;
    // Whether the setting is currently inverted because the modifier is held.
    bool modifierHeld = false;
 
    CheckboxOrModifierState() {}
 
    CheckboxOrModifierState( bool baseValue ) : baseValue( baseValue ) {}
 
    // You usually want to read this instead of the variables above.
    // Returns `baseValue`, but inverted if `modifierHeld` is set.
    [[nodiscard]] explicit operator bool() const { return baseValue != modifierHeld; }
};
 
MRVIEWER_API bool checkboxOrModifier( const char* label, CheckboxOrModifierState& value, int modifiers, int respectedModifiers = -1, std::optional<bool> valueOverride = {} );
 
 
MRVIEWER_API bool radioButton( const char* label, int* value, int valButton );
MRVIEWER_API bool radioButtonOrFixedValue( const char* label, int* value, int valButton, std::optional<int> valueOverride );
 
struct RadioButtonOrModifierState
{
    // The permanent value of this setting, as set by the user by clicking the radio button.
    int value{};
    // The value that is displayed, and to be used - can differ from `value` if modifiers are pressed.
    int effectiveValue{};
 
    // The effective value, affected by modifiers.
    [[nodiscard]] explicit operator int() const
    {
        return effectiveValue;
    }
};
 
MRVIEWER_API bool radioButtonOrModifier( const char* label, RadioButtonOrModifierState& value, int valButton, int modifiers, int respectedModifiers = -1, std::optional<int> valueOverride = {} );
 
MRVIEWER_API bool colorEdit4( const char* label, Vector4f& color, ImGuiColorEditFlags flags = ImGuiColorEditFlags_None );
MRVIEWER_API bool colorEdit4( const char* label, Color& color, ImGuiColorEditFlags flags = ImGuiColorEditFlags_None );
 
MRVIEWER_API bool combo( const char* label, int* v, const std::vector<std::string>& options,
    bool showPreview = true, const std::vector<std::string>& tooltips = {}, const std::string& defaultText = "Not selected" );
 
MRVIEWER_API bool beginCombo( const char* label, const std::string& text = "Not selected", bool showPreview = true );
MRVIEWER_API void endCombo( bool showPreview = true );
 
MRVIEWER_API bool inputText( const char* label, std::string& str, ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
MRVIEWER_API bool inputTextIntoArray( const char* label, char* array, std::size_t size, ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
 
MRVIEWER_API bool inputTextMultiline( const char* label, std::string& str, const ImVec2& size = ImVec2(), ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
MRVIEWER_API bool inputTextIntoArrayMultiline( const char* label, char* buf, size_t buf_size, const ImVec2& size = ImVec2(), ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
 
struct CachedTextSize
{
    std::optional<ImVec2> cachedSize; // Reset this when manually modifying the text.
};
MRVIEWER_API bool inputTextMultilineFullyScrollable( CachedTextSize& cache, const char* label, std::string& str, const ImVec2& size = ImVec2(), ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
MRVIEWER_API bool inputTextIntoArrayMultilineFullyScrollable( CachedTextSize& cache, const char* label, char* buf, size_t buf_size, const ImVec2& size = ImVec2(), ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
 
MRVIEWER_API bool inputTextCentered( const char* label, std::string& str, float width = 0.0f, ImGuiInputTextFlags flags = 0, ImGuiInputTextCallback callback = nullptr, void* user_data = nullptr );
 
MRVIEWER_API void inputTextCenteredReadOnly( const char* label, const std::string& str, float width = 0.0f, const std::optional<ImVec4>& textColor = {}, const std::optional<ImVec4>& labelColor = {} );
 
 
namespace detail
{
    // A type-erased slider.
    MRVIEWER_API bool genericSlider( const char* label, ImGuiDataType data_type, void* p_data, const void* p_min, const void* p_max, const char* format, ImGuiSliderFlags flags );
 
    // Whether `T` is a scalar type that we can use with our widgets.
    template <typename T>
    concept Scalar = std::is_arithmetic_v<T> && !std::is_same_v<T, bool>;
 
    // Whether `T` is a scalar or vector that we can use with our widgets.
    template <typename T>
    concept VectorOrScalar = Scalar<typename VectorTraits<T>::BaseType>;
 
    // Whether `Bound` is a valid min/max bound for `Target`.
    // That is, either the same type, or if `Target` is a vector, `Bound` can also be a scalar of the same type.
    template <typename Bound, typename Target>
    concept ValidBoundForTargetType =
        std::same_as<Bound, Target> ||
        ( VectorTraits<Bound>::size == 1 && std::same_as<typename VectorTraits<Bound>::BaseType, typename VectorTraits<Target>::BaseType> );
 
    // Whether `Speed` is a valid drag speed type for `Target`.
    // That is, either a single/vector of `float` or the same type as target (or its element if it's a vector).
    template <typename Speed, typename Target>
    concept ValidDragSpeedForTargetType =
        std::same_as<Speed, typename VectorTraits<Target>::BaseType> || std::same_as<Speed, float> ||
        std::same_as<Speed, Target> || std::same_as<Speed, typename VectorTraits<Target>::template ChangeBase<float>>;
 
    // A common code for sliders and other widgets dealing with measurement units.
    // `E` must be explicitly set to a measurement unit enum. The other template parameters are deduced.
    // `label` is the widget label, `v` is the target value.
    // `func` draws the widget for an individual scalar. We call it more than once for vectors.
    // `func` is `( const char* label, auto& elem, int i ) -> bool`.
    // It receives `elem` already converted to the display units (so you must convert min/max bounds manually). `i` is the element index for vectors.
    // When `v` is integral, `func` will be instantiated for both integral and floating-point element type. The latter is required if we're doing conversions.
    // NOTE: For integral `v`, in `func` you must look at the type of `elem` and convert your min/max bounds (etc) to the same type.
    // Notice `unitParams` being accepted by an lvalue reference. For convenience, we reset the `sourceUnit` in it before calling the user callback,
    //   since at that point no further conversions are necessary.
    template <UnitEnum E, VectorOrScalar T, typename F>
    [[nodiscard]] bool unitWidget( const char* label, T& v, UnitToStringParams<E>& unitParams, F&& func );
 
}
 
// Default flags for `slider()` and `drag()` below.
inline constexpr int defaultSliderFlags = ImGuiSliderFlags_AlwaysClamp;
 
// Default drag speed for `UI::drag()`.
template <UnitEnum E, detail::VectorOrScalar T>
requires ( VectorTraits<T>::size == 1 )
[[nodiscard]] float getDefaultDragSpeed();
 
// Default step speed for `UI::input()`.
template <UnitEnum E, detail::VectorOrScalar T, detail::VectorOrScalar TargetType>
[[nodiscard]] T getDefaultStep( bool fast );
 
// Draw a slider.
// `E` must be specified explicitly, to one of: `NoUnit` `LengthUnit`, `AngleUnit`, ...
// By default, for angles `v` will be converted to degrees for display (but `vMin`, `vMax` are still in radians, same as `v`),
//   while length and unit-less values will be left as is. This can be customized in `unitParams` or globally (see `MRUnits.h`).
template <UnitEnum E, detail::VectorOrScalar T, detail::ValidBoundForTargetType<T> U = typename VectorTraits<T>::BaseType>
bool slider( const char* label, T& v, const U& vMin, const U& vMax, UnitToStringParams<E> unitParams = {}, ImGuiSliderFlags flags = defaultSliderFlags );
 
// Draw a dragging widget. Also includes [+] and [-] buttons (for integers only by default_, like `ImGui::Input`).
// `E` must be specified explicitly, to one of: `NoUnit` `LengthUnit`, `AngleUnit`, ...
// By default, for angles `v` will be converted to degrees for display (but `vSpeed` is still in radians, same as `v`),
//   while length and unit-less values will be left as is. This can be customized in `unitParams` or globally (see `MRUnits.h`).
// If only the min limit is specified, then the max limit is assumed to be the largest number.
template <UnitEnum E, detail::VectorOrScalar T, detail::ValidDragSpeedForTargetType<T> SpeedType = float, detail::ValidBoundForTargetType<T> U = typename VectorTraits<T>::BaseType>
bool drag( const char* label, T& v, SpeedType vSpeed = getDefaultDragSpeed<E, SpeedType>(), const U& vMin = std::numeric_limits<U>::lowest(), const U& vMax = std::numeric_limits<U>::max(), UnitToStringParams<E> unitParams = {}, ImGuiSliderFlags flags = defaultSliderFlags, const U& step = getDefaultStep<E, U, T>( false ), const U& stepFast = getDefaultStep<E, U, T>( true ) );
 
// Like `drag()`, but clicking it immediately activates text input, so it's not actually draggable.
template <UnitEnum E, detail::VectorOrScalar T, detail::ValidBoundForTargetType<T> U = typename VectorTraits<T>::BaseType>
bool input( const char* label, T& v, const U& vMin = std::numeric_limits<U>::lowest(), const U& vMax = std::numeric_limits<U>::max(), UnitToStringParams<E> unitParams = {}, ImGuiSliderFlags flags = defaultSliderFlags );
 
// Draw a read-only copyable value.
// `E` must be specified explicitly, to one of: `NoUnit` `LengthUnit`, `AngleUnit`, ...
// By default, for angles `v` will be converted to degrees for display, while length and unit-less values will be left as is.
// This can be customized in `unitParams` or globally (see `MRUnits.h`).
template <UnitEnum E, detail::VectorOrScalar T>
void readOnlyValue( const char* label, const T& v, std::optional<ImVec4> textColor = {}, UnitToStringParams<E> unitParams = {}, std::optional<ImVec4> labelColor = {} );
 
 
// A generic wrapper for drawing plus-minus drags/inputs/etc that can be toggled between symmetric and asymmetric mode.
// Prefer `inputPlusMinus()` and other functions written on top of this one.
// `func` is a `(const char* subLabel, T& value, const UnitToStringParams<E>& subUnitParams) -> bool`, draw your widget there with the automatic width,
//   the specified label and value, and return its return value. `value` will receive either `plus` or `minus`.
template <UnitEnum E, detail::Scalar T, typename F>
bool plusMinusGeneric( const char* label, T& plus, T& minus, UnitToStringParams<E> unitToStringParams, F&& func );
 
// A `drag()` for two numbers that can be toggled between symmetric and asymmetric mode.
// Notice the `wrapFunc` parameter. If specified, it is a `(const char* subLabel, T& value, auto&& f) -> bool` lambda that must do `return f();`.
//   That is called for each of the two plus/minus parts of the widget, and lets you e.g. set a custom style for those.
// Here we intentionally don't allow passing the step values, that wouldn't render too well.
template <UnitEnum E, detail::Scalar T, detail::ValidDragSpeedForTargetType<T> SpeedType = float, typename F = std::nullptr_t>
bool dragPlusMinus( const char* label, T& plus, T& minus, SpeedType speed = getDefaultDragSpeed<E, SpeedType>(), T plusMin = T{}, T plusMax = std::numeric_limits<T>::max(), UnitToStringParams<E> unitParams = {}, ImGuiSliderFlags flags = defaultSliderFlags, F&& wrapFunc = nullptr );
 
// An `input()` for two numbers that can be toggled between symmetric and asymmetric mode.
// Notice the `wrapFunc` parameter. If specified, it is a `(const char* subLabel, T& value, auto&& f) -> bool` lambda that must do `return f();`.
//   That is called for each of the two plus/minus parts of the widget, and lets you e.g. set a custom style for those.
template <UnitEnum E, detail::Scalar T, typename F = std::nullptr_t>
bool inputPlusMinus( const char* label, T& plus, T& minus, T plusMin = T{}, T plusMax = std::numeric_limits<T>::max(), UnitToStringParams<E> unitParams = {}, ImGuiSliderFlags flags = defaultSliderFlags, F&& wrapFunc = nullptr );
 
 
MRVIEWER_API const std::pair<const char*, ImU32>& notificationChar( NotificationType type );
 
MRVIEWER_API void mouseControlHint( ImGuiMouseButton btn, const std::string& hint );
 
MRVIEWER_API void transparentText( const char* fmt, ... );
MRVIEWER_API void transparentTextWrapped( const char* fmt, ... );
MRVIEWER_API void notificationFrame( NotificationType type, const std::string& str );
 
MRVIEWER_API void setTooltipIfHovered( const std::string& text );
 
struct SeparatorParams
{
    const ImGuiImage* icon{ nullptr };
 
    Vector2f iconSize; 
 
    std::string label;
 
    std::string suffix;
 
    std::optional<Color> suffixFrameColor;
 
    bool forceImGuiSpacing = false;
 
    float extraScale = 1;
};
 
MRVIEWER_API void separator( const SeparatorParams& params );
 
MRVIEWER_API void separator( const std::string& text = "", int issueCount = -1 );
MRVIEWER_API void separator(
    const std::string& text,
    const ImVec4& color,
    const std::string& issueCount );
// separator line with icon and text
// iconSize icon size without scaling
MRVIEWER_API void separator( const ImGuiImage& icon, const std::string& text, const Vector2f& iconSize = { 24.f, 24.f } );
MRVIEWER_API void separator( const std::string& iconName, const std::string& text, const Vector2f& iconSize = { 24.f, 24.f } );
 
MRVIEWER_API void progressBar( float fraction, const Vector2f& size = Vector2f( -1, 0 ) );
 
// create and append items into a TabBar: see corresponding ImGui:: functions
MRVIEWER_API bool beginTabBar( const char* str_id, ImGuiTabBarFlags flags = 0 );
MRVIEWER_API void endTabBar();
MRVIEWER_API bool beginTabItem( const char* label, bool* p_open = NULL, ImGuiTabItemFlags flags = 0 );
MRVIEWER_API void endTabItem();
 
MRVIEWER_API void alignTextToFramePadding( float padding );
MRVIEWER_API void alignTextToControl( float controlHeight );
MRVIEWER_API void alignTextToRadioButton();
MRVIEWER_API void alignTextToCheckBox();
MRVIEWER_API void alignTextToButton();
 
MRVIEWER_API void highlightWindowArea( const ImVec2& min = {-1.0f, -1.0f}, const ImVec2& max = { -1.0f, -1.0f } );
 
struct CustomConfigModalSettings
{
    std::string configName;
    std::string imGuiIdKey;
    std::filesystem::path configDirectory;
    std::string* inputName{ nullptr };
    bool inputNameDialog = true;
    bool triggerSave = false;
    bool warnExisting = true;
    std::function<bool( const std::string& name )> onSave;
    
    MRVIEWER_API std::string popupName() const;
};
 
MRVIEWER_API void saveCustomConfigModal(const CustomConfigModalSettings& settings );
 
// While this exists, it temporarily disables in the given list the flags with 0 bits in the given mask
class Disabler
{
    ImDrawList& list;
    ImDrawFlags oldFlags{};
 
public:
    Disabler( ImDrawList& list, ImDrawFlags mask )
        : list( list ), oldFlags( list.Flags )
    {
        list.Flags &= mask;
    }
 
    Disabler( const Disabler& ) = delete;
    Disabler& operator=( const Disabler& ) = delete;
 
    ~Disabler()
    {
        list.Flags = oldFlags;
    }
};
 
// While this exists, it temporarily disables antialiasing for the lines drawn to this list.
class LineAntialiasingDisabler : Disabler
{
public:
    LineAntialiasingDisabler( ImDrawList& list ) : Disabler( list, ~ImDrawListFlags_AntiAliasedLines )
    {
    }
};
 
} // namespace UI
 
}
 
#include "MRUIStyle.ipp"