Subversion Repositories tpanel

/*

 * Copyright (C) 2020 to 2023 by Andreas Theofilu <andreas@theosys.at>

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 3 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA

 */

#ifndef __TBUTTON_H__

#define __TBUTTON_H__

#include <string>

#include <vector>

#include <map>

#include <functional>

#include <thread>

#include <include/core/SkImage.h>

#include <include/core/SkCanvas.h>

#include <include/core/SkBitmap.h>

#include "texpat++.h"

#include "tpalette.h"

#include "tcolor.h"

#include "tfont.h"

#include "tamxnet.h"

#include "ttimer.h"

#include "timagerefresh.h"

#include "tsystem.h"

#include "tintborder.h"

#define ORD_ELEM_COUNT  5

extern bool prg_stopped;

extern bool _restart_;

class SkFont;

class SkTextBlob;

class TBitmap;

struct RESOURCE_T;

namespace Button

{

#   define STATE_BASE   0

#   define STATE_OFF    0

#   define STATE_ON     1

#   define STATE_1      0

#   define STATE_2      1

#   define STATE_3      2

#   define STATE_4      3

#   define STATE_5      4

#   define STATE_6      5

#   define STATE_7      6

#   define STATE_8      7

#   define STATE_ALL    -1

#   define HANDLE_UNDEF 0

    typedef struct SYSTEF_t         // Text effect names

    {

        int idx{0};

        std::string name;

    }SYSTEF_t;

    typedef enum TEXT_ORIENTATION

    {

        ORI_ABSOLUT,

        ORI_TOP_LEFT,

        ORI_TOP_MIDDLE,

        ORI_TOP_RIGHT,

        ORI_CENTER_LEFT,

        ORI_CENTER_MIDDLE,		// default

        ORI_CENTER_RIGHT,

        ORI_BOTTOM_LEFT,

        ORI_BOTTOM_MIDDLE,

        ORI_BOTTOM_RIGHT

    } TEXT_ORIENTATION;

    typedef enum TEXT_EFFECT

    {

        EFFECT_NONE,

        EFFECT_OUTLINE_S,

        EFFECT_OUTLINE_M,

        EFFECT_OUTLINE_L,

        EFFECT_OUTLINE_X,

        EFFECT_GLOW_S,

        EFFECT_GLOW_M,

        EFFECT_GLOW_L,

        EFFECT_GLOW_X,

        EFFECT_SOFT_DROP_SHADOW_1,

        EFFECT_SOFT_DROP_SHADOW_2,

        EFFECT_SOFT_DROP_SHADOW_3,

        EFFECT_SOFT_DROP_SHADOW_4,

        EFFECT_SOFT_DROP_SHADOW_5,

        EFFECT_SOFT_DROP_SHADOW_6,

        EFFECT_SOFT_DROP_SHADOW_7,

        EFFECT_SOFT_DROP_SHADOW_8,

        EFFECT_MEDIUM_DROP_SHADOW_1,

        EFFECT_MEDIUM_DROP_SHADOW_2,

        EFFECT_MEDIUM_DROP_SHADOW_3,

        EFFECT_MEDIUM_DROP_SHADOW_4,

        EFFECT_MEDIUM_DROP_SHADOW_5,

        EFFECT_MEDIUM_DROP_SHADOW_6,

        EFFECT_MEDIUM_DROP_SHADOW_7,

        EFFECT_MEDIUM_DROP_SHADOW_8,

        EFFECT_HARD_DROP_SHADOW_1,

        EFFECT_HARD_DROP_SHADOW_2,

        EFFECT_HARD_DROP_SHADOW_3,

        EFFECT_HARD_DROP_SHADOW_4,

        EFFECT_HARD_DROP_SHADOW_5,

        EFFECT_HARD_DROP_SHADOW_6,

        EFFECT_HARD_DROP_SHADOW_7,

        EFFECT_HARD_DROP_SHADOW_8,

        EFFECT_SOFT_DROP_SHADOW_1_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_2_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_3_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_4_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_5_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_6_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_7_WITH_OUTLINE,

        EFFECT_SOFT_DROP_SHADOW_8_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_1_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_2_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_3_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_4_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_5_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_6_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_7_WITH_OUTLINE,

        EFFECT_MEDIUM_DROP_SHADOW_8_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_1_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_2_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_3_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_4_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_5_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_6_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_7_WITH_OUTLINE,

        EFFECT_HARD_DROP_SHADOW_8_WITH_OUTLINE

    }TEXT_EFFECT;

    typedef enum DRAW_ORDER

    {

        ORD_ELEM_NONE,

        ORD_ELEM_FILL,

        ORD_ELEM_BITMAP,

        ORD_ELEM_ICON,

        ORD_ELEM_TEXT,

        ORD_ELEM_BORDER

    }DRAW_ORDER;

    typedef enum FEEDBACK

    {

        FB_NONE,

        FB_CHANNEL,

        FB_INV_CHANNEL,     // inverted channel

        FB_ALWAYS_ON,

        FB_MOMENTARY,

        FB_BLINK

    } FEEDBACK;

    typedef enum PMIX

    {

        PMIX_MULTIPLY,

        PMIX_XOR,

        PMIX_SCREEN,

        PMIX_SRC,

        PMIX_DST,

        PMIX_SRCOVER,

        PMIX_SRCTOP,

        PMIX_DSTTOP,

        PMIX_PLUS

    }PMIX;

    typedef enum SUBVIEW_POSITION_t

    {

        SVP_CENTER,

        SVP_LEFT_TOP,

        SVP_RIGHT_BOTTOM

    }SUBVIEW_POSITION_t;

    typedef struct SR_T

    {

        int number{0};

        std::string _do;        // Order on how to show a multistate bargraph (010203...)

        std::string bs;         // Frame type (circle, ...)

        std::string mi;         // Chameleon image

        int mi_width{0};        // Width of image

        int mi_height{0};       // Height of image

        std::string cb;         // Border color

        std::string cf;         // Fill color

        std::string ct;         // Text Color

        std::string ec;         // Text effect color

        std::string bm;         // bitmap file name

        std::string sd;         // Sound file to play

        int bm_width{0};        // Width of image

        int bm_height{0};       // Height of image

        bool dynamic{false};    // TRUE = moving image

        int sb{0};              // Index to external graphics download

        int ii{0};              // Icon index number

        int ix{0};              // Icon X position

        int iy{0};              // Icon Y position

        int ji{5};              // Icon style / position like "jt", default 5 = center+middle

        int jb{5};              // Image position (center, left, ...), default 5 = center+middle

        int bx{0};              // Absolute image position x

        int by{0};              // Absolute image position y

        int fi{0};              // Font index

        std::string te;         // Text

        TEXT_ORIENTATION jt{ORI_CENTER_MIDDLE}; // Text orientation

        int tx{0};              // Text X position

        int ty{0};              // Text Y position

        int ww{0};              // line break when 1

        int et{0};              // Text effect (^TEF)

        int oo{-1};             // Over all opacity

    } SR_T;

    typedef struct EXTBUTTON_t

    {

        BUTTONTYPE type;

        int bi{0};              // button ID

        std::string na;         // name

        int lt{0};              // pixel from left

        int tp{0};              // pixel from top

        int wt{0};              // width

        int ht{0};              // height

        int zo{0};              // Z-Order

        std::string hs;         // bounding, ...

        std::string bs;         // Border style (circle, ...)

        FEEDBACK fb{FB_NONE};   // Feedback type (momentary, ...)

        int ap{1};              // Address port (default: 1)

        int ad{0};              // Address channel

        int lp{1};              // Level port (default: 1)

        int lv{0};              // Level code

        std::string dr;         // Level "horizontal" or "vertical"

        int lu{0};              // Animate time up (Bargraph)

        int ld{0};              // Animate time down (Bargraph)

        int rl{0};              // Range low

        int rh{0};              // Range high

        int rn{0};              // Bargraph: Range drag increment

        std::string sc;         // Color of slider (for bargraph)

        std::vector<SR_T> sr;

    }EXTBUTTON_t;

    typedef struct PUSH_FUNC

    {

        std::string pfType; // command to execute when button was pushed

        std::string pfName; // Name of popup

    } PUSH_FUNC_T;

    typedef enum CENTER_CODE

    {

        SC_ICON = 0,

        SC_BITMAP,

        SC_TEXT

    }CENTER_CODE;

    typedef struct POSITION_t

    {

        int width{0};

        int height{0};

        int left{1};

        int top{1};

        bool overflow{false};

        bool valid{false};

    }POSITION_t;

    typedef struct IMAGE_SIZE_t

    {

        int width{0};

        int height{0};

    }IMAGE_SIZE_t;

    typedef struct THR_REFRESH_t

    {

        ulong handle{0};

        ulong parent{0};

        int bi{0};

        TImageRefresh *mImageRefresh{nullptr};

        THR_REFRESH_t *next{nullptr};

    }THR_REFRESH_t;

    typedef struct BITMAP_t

    {

        unsigned char *buffer{nullptr};

        int left{0};

        int top{0};

        int width{0};

        int height{0};

        size_t rowBytes{0};

    }BITMAP_t;

    typedef struct BITMAP_CACHE

    {

        ulong handle{0};

        ulong parent{0};

        int left{0};

        int top{0};

        int width{0};

        int height{0};

        int bi{0};

        bool show{false};

        bool ready{false};

        SkBitmap bitmap;

    }BITMAP_CACHE;

#   define LIST_IMAGE_CELL     1

#   define LIST_TEXT_PRIMARY   2

#   define LIST_TEXT_SECONDARY 4

    typedef enum LIST_SORT

    {

        LIST_SORT_NONE,

        LIST_SORT_ASC,

        LIST_SORT_DESC,

        LIST_SORT_OVERRIDE

    }LIST_SORT;

    class TButton : public TSystem, public Border::TIntBorder

    {

        public:

            TButton();

            ~TButton();

            /**

             * The following function parses the parameters of a particular

             * button and creates a new button. This function is called either

             * from class TPage or TSubPage when a page or subpage is created.

             *

             * @param xml     A pointer to the XML reader

             * @param node    A pointer to the actual node in the XML tree.

             * @return On success the last index processed. On error

             * TExpat::npos is returned.

             */

            size_t initialize(Expat::TExpat *xml, size_t index);

            /**

             * Returns the button index. This is a unique number inside a page

             * or subpage.

             *

             * @return return the button index number as defined in the

             * configuration file.

             */

            int getButtonIndex() { return bi; }

            /**

             * Returns the name of the button.

             */

            std::string& getButtonName() { return na; }

            /**

             * Returns the description of the button, if there is one.

             */

            std::string& getButtonDescription() { return bd; }

            /**

             * Returns the width of the button in pixels.

             */

            int getWidth() { return wt; }

            /**

             * Returns the height of the button in pixels.

             */

            int getHeight() { return ht; }

            /**

             * Returns the left position in pixels.

             */

            int getLeftPosition() { return lt; }

            /**

             * Returns the top position of the button in pixels.

             */

            int getTopPosition() { return tp; }

            /**

             * Returns the Z-order. This number marks the order the buttons

             * are drawed on the screen. Inside a page or subpage the buttons

             * are always sorted.

             */

            int getZOrder() { return zo; }

            /**

             * Returns the type of the button.

             */

            BUTTONTYPE getButtonType() { return type; }

            /**

             * Set font file name and optional the size

             *

             * @param name  File name of the font

             * @param size  The size of the font in PT

             * @param inst  The instance of the button

             *

             * @return TRUE success

             */

            bool setFontFileName(const std::string& name, int size, int inst);

            /**

             * Set font name.

             *

             * @param name  The font name

             * @param inst  The instance of the button

             *

             * @return TRUE success

             */

            bool setFontName(const std::string& name, int inst);

            std::string& getName() { return na; }

            int getRangeLow() { return rl; }

            int getRangeHigh() { return rh; }

            int getStateCount() { return stateCount; }

            int getAddressPort() { return ap; }

            int getAddressChannel() { return ad; }

            int getChannelNumber() { return ch; }

            int getChannelPort() { return cp; }

            int getLevelPort() { return lp; }

            int getLevelValue() { return lv; }

            std::string getText(int inst=0);

            std::string getTextColor(int inst=0);

            std::string getTextEffectColor(int inst=0);

            void setTextEffectColor(const std::string& ec, int inst=-1);

            bool setTextEffectColorOnly(const std::string& ec, int inst=-1);

            int getTextEffect(int inst=0);

            void setTextEffect(int et, int inst=-1);

            std::string getTextEffectName(int inst=0);

            void setTextEffectName(const std::string& name, int inst=-1);

            std::string getFillColor(int inst=0);

            std::string getBitmapName(int inst=0);

            bool isSingleLine() { return ( dt.compare("multiple") != 0); }

            bool isMultiLine() { return ( dt.compare("multiple") == 0); }

            int getTextMaxChars() { return mt; }

            void setTextMaxChars(int m) { mt = m; }

            bool getTextWordWrap(int inst=0);

            bool setTextWordWrap(bool ww, int inst=-1);

            int getFontIndex(int inst=0);

            bool setFontIndex(int fi, int inst=-1);

            int getIconIndex(int inst=0);

            std::string getSound(int inst=0);

            void setSound(const std::string& sd, int inst=-1);

            bool getDynamic(int inst=0);

            void setDynamic(int d, int inst=-1);

            int getNumberInstances() { return (int)sr.size(); }

            int getActiveInstance() { return mActInstance; }

            ulong getHandle() { return mHandle; }

            ulong getParent() { return (mHandle & 0xffff0000); }

            void setActiveInstance(int inst);

            void setEnable(bool en) { mEnabled = en; }

            bool isEnabled() { return mEnabled; }

            void setHandle(ulong handle) { mHandle = handle; };

            void setPalette(TPalette *pal) { mPalette = pal; }

            void setParentWidth(int width) { mParentWidth = width; }

            void setParentHeight(int height) { mParentHeight = height; }

            void setParentSize(int width, int height) { mParentWidth = width; mParentHeight = height; }

            void setFonts(TFont *ft) { mFonts = ft; }

            void setGlobalOpacity(int oo) { if (oo >= 0 && oo <= 255) mGlobalOO = oo; }

            void setVisible(bool v) { visible = v; hd = (v ? 0 : 1); }

            bool isVisible() { return visible; }

            bool isSubViewVertical() { return on == "vert"; }

            bool haveListContent() { return _getListContent != nullptr; }

            bool haveListRow() { return _getListRow != nullptr; }

            int getSubViewID() { return st; }

            bool getSubViewScrollbar() { return (ba == 1 ? true : false); }

            int getSubViewScrollbarOffset() { return (ba > 0 ? bo : 0); }

            bool getWrapSubViewPages() { return (ws != 0 ? true : false); }

            bool isFocused() { return mHasFocus; }

            int getTextCursorPosition() { return mCursorPosition; }

            SUBVIEW_POSITION_t getSubViewAnchor();

            std::function<std::vector<std::string>(ulong handle, int ap, int ta, int ti, int rows, int columns)> getCallbackListContent() { return _getListContent; }

            std::function<std::string(int ti, int row)> getCallbackListRow() { return _getListRow; }

            std::function<void (TButton *button)> getCallbackGlobalSettings() { return _getGlobalSettings; };

            /**

             * @brief setBitmap Sets a new bitmap to the button

             * If there was already a bitmap on this button and if this bitmap

             * is different from the one in \p file, then it is erased.

             * The new bitmap file name is set and it will be loaded and created.

             *

             * @param file      File name of a bitmap file.

             * @param instance  The instance where to put the new bitmap. If

             *                  this is 0, the bitmap is set on all instances.

             * @return TRUE if no errors occures, otherwise FALSE.

             */

            bool setBitmap(const std::string& file, int instance);

            /**

             * @brief setCameleon Sets a new cameleon bitmap to the button

             * If there was already a cameleon bitmap on this button and if this

             * cameleon bitmap is different from the one in \p file, then it is

             * erased. The new cameleon bitmap file name is set and it will be

             * loaded and created.

             *

             * @param file      File name of a cameleon bitmap file.

             * @param instance  The instance where to put the new bitmap. If

             *                  this is 0, the bitmap is set on all instances.

             * @return TRUE if no errors occures, otherwise FALSE.

             */

            bool setCameleon(const std::string& file, int instance);

            /**

             * @brief setOpacity Sets the opacity of this button

             *

             * @param op        The opacity in a reange of 0 to 255.

             * @param instance  The instance where to put the new bitmap. If

             *                  this is 0, the bitmap is set on all instances.

             * @return TRUE if no errors occures, otherwise FALSE.

             */

            bool setOpacity(int op, int instance);

            int getOpacity(int inst=0);

            int getListAp() { return ap; }

            int getListTa() { return ta; }

            int getListTi() { return ti; }

            int getListNumRows() { return tr; }

            int getListNumCols() { return tc; }

            int getSubViewSpace() { return sa; }

            std::string getBounding() { return hs; }

            bool setFont(int id, int instance);

            bool setFontOnly(int id, int instance);

            void setTop(int top);

            void setLeft(int left);

            void setLeftTop(int left, int top);

            void setRectangle(int left, int top, int right, int bottom);

            void getRectangle(int *left, int *top, int *height, int *width);

            void setResourceName(const std::string& name, int instance);

            int getBitmapJustification(int *x, int *y, int instance);

            void setBitmapJustification(int j, int x, int y, int instance);

            int getIconJustification(int *x, int *y, int instance);

            void setIconJustification(int j, int x, int y, int instance);

            int getTextJustification(int *x, int *y, int instance);

            void setTextJustification(int j, int x, int y, int instance);

            bool setTextJustificationOnly(int j, int x, int y, int instance);

            bool startAnimation(int start, int end, int time);

            /**

             * @brief registerSystemButton registers the button as a system button.

             *

             * If the button is a system button, than it has special functions.

             * The action of the button depends on the kind of system button.

             */

            void registerSystemButton();

            bool isSystemButton();

            void addPushFunction(std::string& func, std::string& page);

            void clearPushFunctions() { pushFunc.clear(); }

            void clearPushFunction(const std::string& action);

            void refresh();

            /**

             * Sets a particular instance of the button active. This implies

             * a redraw of the button in case the instance is different from

             * the one already visible.

             *

             * @param instance

             * The instance of the button to be activated.

             *

             * @return

             * On error returns FALSE.

             */

            bool setActive(int instance);

            /**

             * Sets an Icon on the button. This implies a redraw of the button

             * in case the instance is different from the one already visible.

             *

             * @param id

             * The id number of the icon.

             *

             * @param instance

             * The instance where the icon should be drawed

             *

             * @return On error returns FALSE.

             */

            bool setIcon(int id, int instance);

            /**

             * Sets an Icon on the button. This implies a redraw of the button

             * in case the instance is different from the one already visible.

             *

             * @param icon

             * The file name of the icon.

             *

             * @param instance

             * The instance where the icon should be drawed

             *

             * @return

             * On error returns FALSE.

             */

            bool setIcon(const std::string& icon, int instance);

            /**

             * Removes an icon from a button. This implies a redraw of the

             * button.

             *

             * @param instance

             * The instance number involved.

             *

             * @return

             * On error returns FALSE.

             */

            bool revokeIcon(int instance);

            /**

             * Set a string to a button.

             *

             * @param txt

             * The text to write on top of  a button.

             *

             * @param instance

             * The instance number involved.

             *

             * @return

             * On error returns FALSE.

             */

            bool setText(const std::string& txt, int instance);

            /**

             * Set a string to a button. This method does not trigger a new

             * drawing of the element.

             *

             * @param txt

             * The text to write on top of  a button.

             *

             * @param instance

             * The instance number involved.

             *

             * @return

             * On error returns FALSE.

             */

            bool setTextOnly(const std::string& txt, int instance);

            /**

             * @brief appendText    Append non-unicode text.

             * @param txt

             * The text to write on top of  a button.

             * @param instance

             * The instance number involved.

             * @return

             * On error returns FALSE.

             */

            bool appendText(const std::string& txt, int instance);

            /**

             * @brief setTextCursorPosition - Set curso position

             * If the button element is of type TEXT_INPUT, this method sets

             * the cursor position. This position comes usually from an input

             * line managed by the graphical surface.

             * If the \b newPos is less then 0 the curser is set in front of the

             * first character. If the value \b newPos is grater then the number

             * of characters then the curser is set after the last character.

             *

             * @param oldPos    The old position of the cursor

             * @param newPos    The new position of the cursor

             */

            void setTextCursorPosition(int oldPos, int newPos);

            /**

             * @brief setTextFocus - Focus of input line changed

             * If the button element is of type TEXT_INPUT, this signals the

             * state of the focus. If \b in is TRUE then the input line got

             * the focus. The ON state of the button is send. If there is

             * a keyboard present the line is then related to this keyboard.

             * If \b in is FALSE the input line lost the focus. The off state

             * is displayed and no more characters are received from a

             * keyboard.

             * If this input line is a system input line, the focus is ignored.

             * It then receives always the keystrokes from a keyboard.

             *

             * @param in    TRUE: Input line got focus, FALSE: input line

             *              lost focus.

             */

            void setTextFocus(bool in);

            /**

             * @brief setBorderColor Set the border color.

             * Set the border color to the specified color. Only if the

             * specified border color is not the same as the current color.

             * Note: Color can be assigned by color name (without spaces),

             * number or R,G,B value (RRGGBB or RRGGBBAA).

             * @param color     the color

             * @param instance

             * The instance number involved.

             * @return

             * On error returns FALSE.

             */

            bool setBorderColor(const std::string& color, int instance);

            /**

             * @brief retrieves the current border color.

             * Determines the current border color of the button and returns

             * the color as a string.

             * @param instance  The instance number of the button.

             * @return

             * If everything went well it returns the color string of the button

             * instance. On error an empty string is returned.

             */

            std::string getBorderColor(int instance);

            /**

             * @brief setFillColor Set the fill color.

             * Set the fill color to the specified color. Only if the

             * specified fill color is not the same as the current color.

             * Note: Color can be assigned by color name (without spaces),

             * number or R,G,B value (RRGGBB or RRGGBBAA).

             * @param color     the color

             * @param instance

             * The instance number involved.

             * @return

             * On error returns FALSE.

             */

            bool setFillColor(const std::string& color, int instance);

            /**

             * @brief setTextColor set the text color.

             * Set the text color to the specified color. Only if the

             * specified text color is not the same as the current color. It

             * redraws the button if the color changed.

             * Note: Color can be assigned by color name (without spaces),

             * number or R,G,B value (RRGGBB or RRGGBBAA).

             * @param color     the color

             * @param instance

             * The instance number involved.

             * @return

             * On error returns FALSE.

             */

            bool setTextColor(const std::string& color, int instance);

            /**

             * @brief setTextColorOnly set the text color only.

             * Set the text color to the specified color. Only if the

             * specified text color is not the same as the current color.

             * Note: Color can be assigned by color name (without spaces),

             * number or R,G,B value (RRGGBB or RRGGBBAA).

             * @param color     the color

             * @param instance

             * The instance number involved.

             * @return

             * On error returns FALSE.

             */

            bool setTextColorOnly(const std::string& color, int instance);

            /**

             * @brief setDrawOrder - Set the button draw order.

             * Determines what order each layer of the button is drawn.

             * @param order     the draw order

             * @param instance

             * The instance number involved.

             * @return

             * On error returns FALSE.

             */

            bool setDrawOrder(const std::string& order, int instance);

            /**

             * @brief setFeedback - Set the feedback type of the button.

             * ONLY works on General-type buttons.

             * @param fb    The feedback type

             * @return On error returns FALSE.

             */

            bool setFeedback(FEEDBACK feedback);

            /**

             * @brief setFeedback - Sets the feedback type.

             * This retrieves the feedback type of a button. Only if the button

             * is a general type one, a valid value is returned.

             *

             * @return The feedback type of a button.

             */

            FEEDBACK getFeedback();

            /**

             * Set a border to a specific border style associated with a border

             * value for those buttons with a defined address range.

             * @param style     The name of the border style

             * @param instance  -1 = style for all instances

             * > 0 means the style is valid only for this instance.

             */

            bool setBorderStyle(const std::string& style, int instance=-1);

            /**

             * Set a border to a specific border style associated with a border

             * value for those buttons with a defined address range.

             * @param style     The index number of the border style

             * @param instance  -1 = style for all instances