#include <Sprite.h>
Inheritance diagram for Sprite: Collaboration diagram for Sprite:A class represents a 2D graphics element in Pooka SDK® application content.
In Pooka SDK®, Sprite is the lowest-level 2D content node, means it is ultimate 2D object presented in 2D content. Sprite's direct container is SceneSprite. The following picture shows sprites (by purple boxes) in Pooka SDK® application hierarchical structure
Remarks Sprite Appearance Properties
Sprite provides large amount of class properties to describe a Sprite appearance. The property combination can generate a vast diversity in Sprite's appearance.
Some of the appearance properties share certain similarities to those defined in CSS (Cascading Style Sheets).
Caution Although some Sprite properties are loosely inspired by CSS properties, there is by no means an one-to-one mapping between them and developers should always refer to Pooka SDK® API reference to get the precise meaning of each Sprite properties.
Remarks Static Sprite vs Interactive Sprite
There are two kinds of Sprite in Pooka SDK® application: static sprites and interactive sprites. Static sprites can only display certain types of information through its text or texture whereas they do not respond to user operations. Interactive sprites, on the other hand, are sprites that can respond to user operations and are UI elements involved in user inter-activities. The property guiType and enumeration GUI_SPRITE_TYPE work together to determine whether a Sprite is a static Sprite or interactive Sprite.
The enumeration type GUI_STATIC defines a static Sprite, that is means this Sprite does not respond to use input (such as mouse or keyboard) and is only used to display some kinds of static information. All other types defines an interactive Sprite.
Note None of the GUI_SPRITE_TYPE type will change the Sprite's look unless the Sprite is themed (see setThemeType). For non-themed sprites, it is developers' responsibility to control the their appearance by properties defined in Sprite class.
Remarks Un-themed Sprite vs Themed Sprite
In Pooka SDK®, a Sprite can be un-themed (by default) or themed:
Remarks Sprites Maintains a Value
Certain types of interactive Sprite can maintain a value. During the application session, the value maintained by sprite may be changed by user operation. For example, the text value of a edit-box sprite can be changed after user editing.
| guiType | Meaning of the Maintained Value | |
|---|---|---|
| check-box | GUI_CHECKBOX | Whether the check-box is checked |
| radio-button | GUI_CHECKBOX (check-box is turned into radio-button when they are grouped together) | Whether the radio-button is selected |
| edit-box | GUI_EDITBOX (edit-box can also appear to be password field) | The text value |
Under certain situations, developers may want to persist the sprite's value across multiple application sessions, there are two options:
True to make the value persistence done by GUI::OGCanvas automatically. Remarks Interactive Sprite vs LWComponent
While a single interactive sprite is capable for certain simple user operations, it can not undertake complicated job, such as a calculator, a color picker, or even a simple drop-down list-box. In this case, a group of sprites work together to compose a UI component to fulfill a complicated task. In order to make these sprite groups reusable, Pooka SDK® provides a class LWComponent help generate light-weight, moduled, fully reusable component that can help easily construct UI for complicated user operations.
Classes | |
| class | DraggingListener |
| class | EditBoxVerificationListener |
| class | RenderListener |
Public Member Functions | |
| Sprite (int x=0, int y=0, int width=-1, int height=-1) | |
| Sprite (const Sprite &another) | |
| virtual | ~Sprite () |
| virtual Sprite & | getClone () |
| virtual void | set (Sprite *another) |
| void | setSize (int width, int height) |
| void | setPosition (int x, int y) |
| void | setDimension (int x, int y, int width, int height) |
| void | setSizePT (int width, int height) |
| void | setPositionPT (int x, int y) |
| void | setDimensionPT (int x, int y, int width, int height) |
| void | setSizeByRef (int xPercentOrExpansion, int yPercentOrExpansion, int reference, int sizingMode, Sprite *anotherSprite=0) |
| void | setPositionByRef (int xGapOrOffset, int yGapOrOffset, int reference, int positioningMode, Sprite *anotherSprite=0) |
| void | setPositionNextToRef (Sprite *anotherSprite, int positioningMode, int distance) |
| void | getAnchorPosition (int anchorType, MiniSTL::Type::OGPoint *position) |
| void | setText (wchar_t *text, bool ignoreEscapeCodeInText=false) |
| wchar_t * | getText () |
| void | setThemeType (int themeType) |
| int | getThemeType () |
| void | getUnformattedTextSize (MiniSTL::Type::OGSize *textSize, int state=Group::STATE_NORMAL, MiniAWT::Graphics::BitmapFont *assumedBitmapFont=0) |
| void | setTextures (Texture *texture, Texture *textureBright, int clipX=-1, int clipY=-1, int clipW=-1, int clipH=-1) |
| void | setHyperLinkDestination (wchar_t *href) |
| wchar_t * | getHyperLinkDestination () |
| void | setSpriteEditBoxAttribute (wchar_t *attribName, int attribValue) |
| int | getSpriteEditBoxAttribute (wchar_t *attribName) |
| bool | setNavigationIndex (wchar_t numericIndex, wchar_t alphabeticIndex, wchar_t specialIndex=0) |
| void | setIndexTokenOffset (int offsetX, int offsetY) |
| int | getIndexTokenOffsetX () |
| int | getIndexTokenOffsetY () |
| Public Member Functions inherited from Group | |
| void | setName (wchar_t *name) |
| wchar_t * | getName () |
| virtual | ~Group () |
| Public Member Functions inherited from Asset | |
| virtual | ~Asset () |
| Public Member Functions inherited from Object | |
| Object () | |
| virtual | ~Object () |
| void | addRef () |
| void | release () |
| virtual wchar_t * | toString () |
| wchar_t * | getClassName (bool keepNameSpace=false) |
| void | syncBegin () |
| void | syncEnd () |
| void | wait (unsigned int timeout=0xFFFFFFFF) |
| void | notify () |
| void | notifyAll () |
Static Public Attributes | |
| static wchar_t * | EDITBOX_ATTR_MULTI_LINE |
| static wchar_t * | EDITBOX_ATTR_MAX_LENGTH |
| static wchar_t * | EDITBOX_ATTR_INPUT_TYPE |
| static wchar_t * | EDITBOX_ATTR_ALLOW_EMPTY |
| static wchar_t * | EDITBOX_ATTR_READ_ONLY |
| static wchar_t * | EDITBOX_ATTR_SHOW_AS_PASSWORD |
Additional Inherited Members | |
| Protected Member Functions inherited from Group | |
| Group () | |
| Protected Member Functions inherited from Asset | |
| Asset () | |
| enum GUI_SPRITE_TYPE |
Enumeration defines the GUI (graphical user interface) type of a Sprite.
Sprite's GUI type tells the role of a Sprite in user interface. For example, some sprites are used to generate a click-able button, a check-box or a hyper-link, these types of Sprite are referred to as interactive sprites; On the other side, some sprites may be used just as static UI elements that only shows some kinds of information, such as a text box, a label or a picture.
See Static Sprite vs Interactive Sprite for more details.
| Enumerator | |
|---|---|
| GUI_STATIC | A static UI element used to show static content such as text, picture, information, etc. |
| GUI_BUTTON | An interactive Sprite used as an interactive button |
| GUI_CHECKBOX | An interactive Sprite used as a interactive check-box |
| GUI_HYPERLINK | An interactive Sprite used as a click-able hyper-link |
| GUI_TIPLINK | An interactive Sprite used as a click-able tip-link |
| GUI_EDITBOX | An interactive Sprite used as a edit-box for text input |
| GUI_LWCOMPONENT | An interactive Sprite used as an interactive light-weight component |
| enum TEXT_ALIGNMENT_MODE |
Enumeration defines the text horizontal alignment mode, the default mode is ALIGH_LEFT.
The default value if ALIGN_LEFT.
| Enumerator | |
|---|---|
| ALIGN_LEFT | Text horizontal left-aligned mode. |
| ALIGN_CENTER | Text horizontal center-aligned mode. |
| ALIGN_RIGHT | Text horizontal right-aligned mode. |
Enumeration defines the text vertical alignment mode, the default mode is ALIGN_V_TOP.
The default value if ALIGN_V_TOP.
| Enumerator | |
|---|---|
| ALIGN_V_TOP | Text vertical top-aligned mode. |
| ALIGN_V_MIDDLE | Text vertical middle-aligned mode. |
| ALIGN_V_BOTTOM | Text vertical bottom-aligned mode. |
Enumeration defines the anchor point types
The anchor point determines the geometrical origin of a Sprite. The anchor type has effect on the following things:
This enumeration is also used by property textureAlignment, which determines how Sprite's texture is aligned with Sprite when it is rendered. See textureAlignment for more details.
| Enumerator | |
|---|---|
| ANCHOR_LEFT_TOP | Anchor point is at the left-top corner of the Sprite's bounding box. |
| ANCHOR_RIGHT_TOP | Anchor point is at the right-top corner of the Sprite's bounding box. |
| ANCHOR_LEFT_BOTTOM | Anchor point is at the left-bottom corner of the Sprite's bounding box. |
| ANCHOR_RIGHT_BOTTOM | Anchor point is at the right-bottom corner of the Sprite's bounding box. |
| ANCHOR_TOP_CENTER | Anchor point is at the top-side-center of the Sprite's bounding box. |
| ANCHOR_BOTTOM_CENTER | Anchor point is at the bottom-side-center of the Sprite's bounding box. |
| ANCHOR_LEFT_CENTER | Anchor point is at the left-side-center of the Sprite's bounding box. |
| ANCHOR_RIGHT_CENTER | Anchor point is at the right-side-center of the Sprite's bounding box. |
| ANCHOR_CENTER | Anchor point is at the center of the Sprite's bounding box. |
Enumeration defines the position-by-reference mode when position a Sprite by another reference Sprite.
| Enumerator | |
|---|---|
| RIGHT_NEXT_TO | The target Sprite is on the right next to the reference Sprite. |
| UP_NEXT_TO | The target Sprite is above and next to the reference Sprite. |
| LEFT_NEXT_TO | The target Sprite is on the left next to the reference Sprite. |
| DOWN_NEXT_TO | The target Sprite is under and next to the reference Sprite. |
| enum EDITBOX_INPUT_TYPES |
Values that represent the input type of a edit-box Sprite.
| Enumerator | |
|---|---|
| EDITBOX_NATURAL_NUMBER | Indicates the sprite-editbox accepts natural numbers, including number 0. |
| EDITBOX_WHOLE_NUMBER | Indicates the sprite-editbox accepts [whole numbers] (positive integer)](https://en.wikipedia.org/wiki/List_of_types_of_numbers). |
| EDITBOX_INTEGER | Indicates the sprite-editbox accepts integer. |
| EDITBOX_REAL_NUMBER | Indicates the sprite-editbox accepts real numbers. |
| EDITBOX_ALPHANUMERIC | Indicates the sprite-editbox accepts POSIX/C Alphanumeric characters. |
| EDITBOX_ANYTHING | Indicates the sprite-editbox accepts any characters. |
| Sprite | ( | int | x = 0, |
| int | y = 0, |
||
| int | width = -1, |
||
| int | height = -1 |
||
| ) |
Constructor.
| x | The x coordinate of the Sprite defined in container SceneSprite's coordinate system, in pixels |
| y | The y coordinate of the Sprite defined in container SceneSprite's coordinate system, in pixels |
| width | The width of the Sprite in pixels |
| height | The height of the Sprite in pixels |
|
virtual |
Destructor.
|
virtual |
Gets a clone of this Sprite and return the reference to the caller.
Reimplemented in TokenSprite.
|
virtual |
| void setSize | ( | int | width, |
| int | height | ||
| ) |
| void setPosition | ( | int | x, |
| int | y | ||
| ) |
| void setDimension | ( | int | x, |
| int | y, | ||
| int | width, | ||
| int | height | ||
| ) |
Sets the size and position of this Sprite.
Tip This is a convenience function to set the size and position of this Sprite. It can also be done by setting value of x, y, width and height directly.
See illustration
| void setSizePT | ( | int | width, |
| int | height | ||
| ) |
| void setPositionPT | ( | int | x, |
| int | y | ||
| ) |
| void setDimensionPT | ( | int | x, |
| int | y, | ||
| int | width, | ||
| int | height | ||
| ) |
Sets the size and position of this Sprite.
Tip This is a convenience function to set the size and position of this Sprite. It can also be done by setting value of x, y, width and height directly.
See illustration
| x | The x coordinate of this Sprite, in points |
| y | The y coordinate of this Sprite, in points |
| width | The desired width of this Sprite, in points |
| height | The desired height of this Sprite, in points |
| void setSizeByRef | ( | int | xPercentOrExpansion, |
| int | yPercentOrExpansion, | ||
| int | reference, | ||
| int | sizingMode, | ||
| Sprite * | anotherSprite = 0 |
||
| ) |
Sets size of this Sprite by a reference.
This function sets the size of this Sprite by a reference, which can be:
The size is determined by the reference and the sizing mode, refer to SceneGraph::Scene::POSITION_AND_SIZE_MODE for more details.
Depends on the argument sizingMode, the first two arguments are used either as percent or expansion (in pixels) relative to the reference.
sizingMode is SceneGraph::Scene::RELATIVE_SIZE_BY_PIXEL: the new size is equal to the reference's size plus applying an expansion specified by arguments xPercentOrExpansion and yPercentOrExpansion.sizingMode is SceneGraph::Scene::RELATIVE_SIZE_BY_PERCENTAGE: the new size is determined by a percentage value specified by arguments xPercentOrExpansion and yPercentOrExpansion relative to the reference's size
| xPercentOrExpansion | The horizontal percent or expansion, relative to the reference. |
| yPercentOrExpansion | The vertical percent or expansion, relative to the reference. |
| reference | The reference type, must be one of constants defined in SceneGraph::Scene::POSITION_AND_SIZE_REFERENCE. |
| sizingMode | The sizing mode, must be one of constants defined in SceneGraph::Scene::POSITION_AND_SIZE_MODE. |
| anotherSprite | Another Sprite as the reference, only used when the argument reference has value equal to SceneGraph::Scene::RELATIVE_TO_SPRITE. |
| void setPositionByRef | ( | int | xGapOrOffset, |
| int | yGapOrOffset, | ||
| int | reference, | ||
| int | positioningMode, | ||
| Sprite * | anotherSprite = 0 |
||
| ) |
Sets position of this Sprite by a reference.
This function sets the position of this Sprite by a reference, which can be:
The position is determined by the reference and the positioning mode, refer SceneGraph::Scene::POSITION_AND_SIZE_MODE for more details.
Depends on the argument positioningMode, the first two arguments are used either as offset (in pixels) or gap (in pixels) relative to one border of the reference.
| How Relative Position Determined | How Arguments Gap/Offset Applied | |
|---|---|---|
| RELATIVE_POS_CENTER | newX: horizontally centered to the reference newY: vertically centered to the reference |
xGapOrOffset:applied as offset yGapOrOffset:applied as offset |
| RELATIVE_POS_H_CENTER | newX: horizontally centered to the reference newY: remained unchanged |
xGapOrOffset:applied as offset yGapOrOffset:applied as offset |
| RELATIVE_POS_V_CENTER | newX: remained unchanged newY: vertically centered to the reference |
xGapOrOffset:applied as offset yGapOrOffset:applied as offset |
| RELATIVE_POS_LEFT | newX: left-aligned to the reference newY: remained unchanged |
xGapOrOffset:applied as gap yGapOrOffset:applied as offset |
| RELATIVE_POS_RIGHT | newX: right-aligned to the reference newY: remained unchanged |
xGapOrOffset:applied as gap yGapOrOffset:applied as offset |
| RELATIVE_POS_TOP | newX: remained unchanged newY: top-aligned to the reference |
xGapOrOffset:applied as offset yGapOrOffset:applied as gap |
| RELATIVE_POS_BOTTOM | newX: remained unchanged newY: bottom-aligned to the reference |
xGapOrOffset:applied as offset yGapOrOffset:applied as gap |
| RELATIVE_POS_LEFTTOP | newX: left-aligned to the reference newY: top-aligned to the reference |
xGapOrOffset:applied as gap yGapOrOffset:applied as gap |
| RELATIVE_POS_RIGHTTOP | newX: right-aligned to the reference newY: top-aligned to the reference |
xGapOrOffset:applied as gap yGapOrOffset:applied as gap |
| RELATIVE_POS_LEFTBOTTOM | newX: left-aligned to the reference newY: bottom-aligned to the reference |
xGapOrOffset:applied as gap yGapOrOffset:applied as gap |
| RELATIVE_POS_RIGHTBOTTOM | newX: right-aligned to the reference newY: bottom-aligned to the reference |
xGapOrOffset:applied as gap yGapOrOffset:applied as gap |
| RELATIVE_POS_LEFTCENTER | newX: left-aligned to the reference newY: vertically centered to the reference |
xGapOrOffset:applied as offset yGapOrOffset:applied as gap |
| RELATIVE_POS_RIGHTCENTER | newX: right-aligned to the reference newY: vertically centered to the reference |
xGapOrOffset:applied as offset yGapOrOffset:applied as gap |
| RELATIVE_POS_TOPCENTER | newX: horizontally centered to the reference newY: top-aligned to the reference |
xGapOrOffset:applied as gap yGapOrOffset:applied as offset |
| RELATIVE_POS_BOTTOMCENTER | newX: horizontally centered to the reference newY: bottom-aligned to the reference |
xGapOrOffset:applied as gap yGapOrOffset:applied as offset |
| xGapOrOffset | The horizontal offset or gap applied to the final position, in pixels. |
| yGapOrOffset | The vertical offset or gap applied to the final position, in pixels. |
| reference | The reference type, must be one of constants defined in SceneGraph::Scene::POSITION_AND_SIZE_REFERENCE. |
| positioningMode | The positioning mode, must be one of constants defined in SceneGraph::Scene::POSITION_AND_SIZE_MODE. |
| anotherSprite | Another Sprite as the reference, only used when the argument reference has value equal to SceneGraph::Scene::RELATIVE_TO_SPRITE. |
| void setPositionNextToRef | ( | Sprite * | anotherSprite, |
| int | positioningMode, | ||
| int | distance | ||
| ) |
Sets position of this Sprite by another reference Sprite.
The position is determined by the reference Sprite and the positioning mode, which must be one of constants defined in enumeration POSITION_NEXT_TO_TYPE. The following chart shows the meaning of each positioning modes:
| How Relative Position Determined | |
|---|---|
| LEFT_NEXT_TO | The target Sprite is on the left next to the reference Sprite |
| RIGHT_NEXT_TO | The target Sprite is on the right next to the reference Sprite |
| UP_NEXT_TO | The target Sprite is above and next to the reference Sprite |
| DOWN_NEXT_TO | The target Sprite is under and next to the reference Sprite |
| anotherSprite | Another Sprite as the reference |
| positioningMode | The positioning mode, must be one of constants defined in POSITION_NEXT_TO_TYPE |
| distance | The distance between this Sprite and thereference Sprite, in pixels. |
| void getAnchorPosition | ( | int | anchorType, |
| MiniSTL::Type::OGPoint * | position | ||
| ) |
Gets this Sprite's anchor position in container SceneSprite's coordinate system, in pixels.
This function calculates anchor point position with a specified anchor point type, the result is the coordinate in container SceneSprite's coordinate system, in pixels.
| anchorType | The desired anchor point type, must be one of constants defined in POSITION_ANCHORPOINT_TYPE. |
| position | An OGPoint used to return the anchor position. |
| void setText | ( | wchar_t * | text, |
| bool | ignoreEscapeCodeInText = false |
||
| ) |
Sets the Sprite's text
The argument text can contains any characters including the reserved OGTemplate separator characters and there is no need to use escape character to encode them. However, if text attribute is assigned by OGTemplate , then reserved separator tokens must be encoded by escape characters, see OGTemplate - Loading Sprite for more details.
For example, the following two lines of code assign the same text to the target sprite:
As the result, the target sprite's text is assigned as Personal [A]: Hello, How are you?. If the argument ignoreEscapeCodeInText is set to True, then the code
will simply do the straight text copy on the target sprite, then the result will be Personal [A]^c Hello^cm How are you?, which might be wrong.
| void setThemeType | ( | int | themeType | ) |
Sets the theme type of this Sprite.
See Un-themed Sprite vs Themed Sprite for more details.
| themeType | The theme type, must be one of constants defined in SpriteTheme::THEME_GUI_TYPE. |
| int getThemeType | ( | ) |
Gets the theme type of this Sprite.
| void getUnformattedTextSize | ( | MiniSTL::Type::OGSize * | textSize, |
| int | state = Group::STATE_NORMAL, |
||
| MiniAWT::Graphics::BitmapFont * | assumedBitmapFont = 0 |
||
| ) |
Gets the size of Sprite's text without the text format ignored.
This function retrieves the size of Sprite's text with related properties in this Sprite, such as textSize, bitmapFont. However, all the format related properties like textFormatted, textAlignment are ignored. The retrieved size (in pixels) is equal to the size of a "bounding box" contains the rendered Sprite's text with condition that the text is rendered in a single line and without any formatting.
| textSize | The size of "bounding box" contains the rendered Sprite's text. |
| state | The state of the Sprite, must be one of constants defined in SceneGraph::Group::state. The default value is SceneGraph::Group::STATE_NORMAL, means normal state. |
| assumedBitmapFont | An assumed BitmapFont given to this Sprite when calculate the size. |
| void setTextures | ( | Texture * | texture, |
| Texture * | textureBright, | ||
| int | clipX = -1, |
||
| int | clipY = -1, |
||
| int | clipW = -1, |
||
| int | clipH = -1 |
||
| ) |
Sets the textures of this Sprite.
Tip This is a convenience function to set the textures of this Sprite. It can also be done by setting value of texture and textureBright directly.
| texture | The texture used when the Sprite is under "normal" state (The Sprite's state is STATE_NORMAL ). |
| textureBright | The texture used when the Sprite is under "active" state (The Sprite's state is STATE_ACTIVE ). |
| clipX | The X coordinate of texture's clipping window, see textureClipX for more details. |
| clipY | The Y coordinate of texture's clipping window, see textureClipY for more details. |
| clipW | The width of texture's clipping window, see textureClipW for more details. |
| clipH | The height of texture's clipping window, see textureClipH for more details. |
| void setHyperLinkDestination | ( | wchar_t * | href | ) |
Sets the hyper-link destination of this Sprite.
If this Sprite is a hyper-link Sprite, i.e., its guiType property is set to GUI_HYPERLINK, then this function can be used to set it destination. The destination is a OGTemplate URLspecified by a C string.
Note If the Sprite is not hyper-link Sprite, this function does nothing.
| href | A OGTemplate URL specified by a C string. |
| wchar_t* getHyperLinkDestination | ( | ) |
Gets the hyper-link destination of this Sprite.
If this Sprite is a hyper-link Sprite, this function returns the hyper-link destination (A OGTemplate URL), otherwise it returns NULL.
| void setSpriteEditBoxAttribute | ( | wchar_t * | attribName, |
| int | attribValue | ||
| ) |
Sets the edit-box attributes of this Sprite if it is an edit-box Sprite.
If this Sprite is an edit-box Sprite, this function sets one edit-box attributes specified by the attribute name. See the following attribute name/value chart.
| Attribute Name | Attribute Value | Meaning |
|---|---|---|
| EDITBOX_ATTR_MULTI_LINE | integer 1 (true) or 0 (false) | Whether this is a multi-line edit-box |
| EDITBOX_ATTR_MAX_LENGTH | integer | Maximum number of characters can be input in this edit-box |
| EDITBOX_ATTR_INPUT_TYPE | integer, must be one of constants defined in EDITBOX_INPUT_TYPES | The input type of a edit-box Sprite, defined by EDITBOX_INPUT_TYPES |
| EDITBOX_ATTR_ALLOW_EMPTY | integer 1 (true) or 0 (false) | Whether this edit-box allows empty input (has 0 characters) |
| EDITBOX_ATTR_READ_ONLY; | integer 1 (true) or 0 (false) | Whether this edit-box is read-only |
| EDITBOX_ATTR_SHOW_AS_PASSWORD; | integer 1 (true) or 0 (false) | Whether this edit-box hides characters that user input (shown as "*") |
Note If the Sprite is not edit-box Sprite, this function does nothing.
| attribName | The attribute name specified by a C string |
| attribValue | The attribute value specified by an integer. If the attribute has boolean value, then use number "1" to represent "true" and number "0" to represent "false". |
| int getSpriteEditBoxAttribute | ( | wchar_t * | attribName | ) |
Gets the edit-box attributes of this Sprite if it is an edit-box Sprite.
If this Sprite is an edit-box Sprite, this function gets one edit-box attributes specified by the attribute name. See function setSpriteEditBoxAttribute for the attribute name and value format. If this Sprite is not an edit-box Sprite, it returns NULL.
| attribName | The attribute name specified by a C string |
| bool setNavigationIndex | ( | wchar_t | numericIndex, |
| wchar_t | alphabeticIndex, | ||
| wchar_t | specialIndex = 0 |
||
| ) |
Sets this Sprite's keyboard navigation index (shortcut).
When the Sprite's container SceneSprite has its keyboard navigation mode set to SceneSprite::NAVIGATION_INDEXENTRY, the keyboard navigation index set by this function can be used to "virtually click" the Sprite by the keyboard shortcut. See SceneSprite::KEYBOARD_NAVIGATION_MODE for details.
The navigation index can be specified by a special navigation index, one of constants defines by OGCanvas::SPECIAL_NAVIGATION_INDEX or by a two-character string which is a combination of one numeric index plus one alphabetic index.
Note Sprite's keyboard navigation index has not effect unless the container SceneSprite has its navigation mode set to SceneSprite::NAVIGATION_INDEXENTRY and the sprite is an interactive sprite .
Note When the attribute is specified by a combination of one numeric index and an alphabetic index, the first index is numeric shortcut and the second index is the alphabetic shortcut.
| numericIndex | Numeric index (shortcut), one of numeric characters ['0', ..., '9'] |
| alphabeticIndex | Alphabetic index (shortcut), one of capital alphabet characters ['A', ..., 'Z'] |
| specialIndex | Special index (shortcut), one of constants defines by GUI::OGCanvas::SPECIAL_NAVIGATION_INDEX. The default value of this argument is 0, indicates there is no special index for this Sprite. |
True if it succeeds, False if it fails. | void setIndexTokenOffset | ( | int | offsetX, |
| int | offsetY | ||
| ) |
Sets the index token text offset.
Note The SceneSprite class has a function SceneSprite::setIndexTokenOffset(), which set the token text offset at the SceneSprite level; This function set per-sprite based token text offset and is applied after the per-scene based token text offset.
| offsetX | The index token X-offset, in pixels |
| offsetY | The index token Y-offset, in pixels |
| int getIndexTokenOffsetX | ( | ) |
Gets the index token text X-offset.
| int getIndexTokenOffsetY | ( | ) |
Gets the index token text Y-offset.
|
static |
A constant wide-char C string ("multiline") used to set or get multi-line attribute of a sprite-based edit-box.
|
static |
A constant wide-char C string ("maxLength") used to set or get max-length attribute of a sprite-based edit-box.
|
static |
A constant wide-char C string ("inputType") used to set or get input-type attribute of a sprite-based edit-box.
|
static |
A constant wide-char C string ("allowEmpty") used to set or get allow-empty attribute of a sprite-based edit-box.
|
static |
A constant wide-char C string ("readOnly") used to set or get read-only attribute of a sprite-based edit-box.
|
static |
A constant wide-char C string ("showAsPassword") used to set or get show-as-password attribute of a sprite-based edit-box.
| int x |
The x coordinate (in pixels) of this Sprite's anchor point (left-top corner by default), defined in the containing SceneSprite coordinate system. The default value is set to 0.
See illustration
| int y |
The y coordinate (in pixels) of this Sprite's anchor point (left-top corner by default), defined in the containing SceneSprite coordinate system. The default value is set to 0.
See illustration
| int z |
The depth position of this Sprite, the default value is set to 0.
Sprite's depth value is not in use until SceneSprite::sortSpriteByZOrder is set to True. In that case, the depth value is the Z-order value used by RenderPipelineSprite to sort all sprites before render them. See SceneSprite::sortSpriteByZOrder for more details.
| int width |
The width in pixels of this Sprite, the default value is set to 0.
See illustration
| int height |
The height in pixels of this Sprite, default value is set to 0.
See illustration
| int color |
The background color of this Sprite.
The default value is CLEAR , means that the Sprite has clear (no) background.
Tip See Sprite Visual Anatomy
Note The "active" counterpart of this property is colorBright.
| int colorBright |
The background color of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ).
The default value is CLEAR , means that the Sprite has clear (no) background.
Tip See Sprite Visual Anatomy
| int colorTransparency |
The transparency level of the background color, in range of [0, 255] where 0 indicates full opacity and 255 indicates full transparency.
The default value is 0.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int outlineColor |
The outline color of this Sprite.
The default value is CLEAR , means that the Sprite has no outline.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int frameColor |
The frame color of this Sprite.
The default value is CLEAR , means that the Sprite has no frame.
Tip See Sprite Visual Anatomy
Note The "active" counterpart of this property is frameColorBright.
| int frameColorBright |
The frame color of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ).
The default value is CLEAR , means that the Sprite has no frame.
Tip See Sprite Visual Anatomy
| int frameBevel |
The frame bevel style of this Sprite, must be one of constants defined in FRAME_BEVEL_TYPE .
The default value is GraphicsKernel::GraphicsEngine::BEVEL_NONE, means that the Sprite has no frame bevel.
Tip See Sprite Visual Anatomy Note The "active" counterpart of this property is frameBevelBright.
| int frameBevelBright |
The frame bevel style of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ), must be one of constants defined in FRAME_BEVEL_TYPE .
The default value is GraphicsKernel::GraphicsEngine::BEVEL_NONE, means that the Sprite has no frame bevel.
Tip See Sprite Visual Anatomy
| int frameThickness |
The frame thickness of this Sprite, measured in pixels.
The default value is 1 point
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| bool frameAsUnderline |
Indicates whether the Sprite's frame should be rendered as underline (when True) or regular frame (when False).
The default value is False
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int cornerCut |
The corner-cut (chamfer) size of this Sprite, measured in pixels.
The default value is 0, means there is no corner-cut.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int anchorPoint |
The anchor point type of this Sprite, must be one of constants defined in POSITION_ANCHORPOINT_TYPE.
The anchor point determines the geometrical origin of a Sprite. The anchor type has effect on numbers of things when the sprite is rendered, see POSITION_ANCHORPOINT_TYPE for more details.
| int textSize |
The text font size of this Sprite, measured in pixels.
The default value is 14 point
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| bool textBold |
Whether the Sprite's text has bold style.
The default value is false
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| bool textItalic |
Whether the Sprite's text has italic style.
The default value is false
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| bool textUnderline |
Whether the Sprite's text has underline style.
The default value is false
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int textColor |
The text color of this Sprite.
The default value is WHITE .
Tip See Sprite Visual Anatomy
Note The "active" counterpart of this property is textColorBright.
| int textColorBright |
The text color of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ).
The default value is WHITE .
Tip See Sprite Visual Anatomy
| int textTransparency |
The transparency level of Sprite's text, in range of [0, 255] where 0 indicates full opacity and 255 indicates full transparency.
The default value is 0.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int textShadow |
The text shadow color of this Sprite.
The default value is CLEAR , means that the Sprite has no shadow.
Tip See Sprite Visual Anatomy
Note The "active" counterpart of this property is textShadowTransparency.
| int textShadowTransparency |
The text shadow color of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ).
The default value is CLEAR , means that the Sprite has no shadow.
Tip See Sprite Visual Anatomy
| bool textFormatted |
Indicates whether the Sprite's text is formatted or not.
The default value is False. When the Sprite's text is not formatted, the text is rendered in a single text line, from left to right, without boundary checking and text aligning. When the Sprite's text is formatted, the text if rendered with format defined by textAlignment and textVAlignment.
Tip In case performance is critical, Sprite's textFormatted property should be set to False since rendering formatted text takes more processor power.
Tip See Sprite Visual Anatomy
| int textAlignment |
The horizontal text alignment of this Sprite, must be one of constants defined in TEXT_ALIGNMENT_MODE.
The default value is ALIGN_LEFT. Tip See Sprite Visual Anatomy
Note This property has no effect unless the property textFormatted is set to True.
| int textVAlignment |
The vertical text alignment of this Sprite, must be one of constants defined in TEXT_V_ALIGNMENT_MODE.
The default value is ALIGN_V_TOP. Tip See Sprite Visual Anatomy
Note This property has no effect unless the property textFormatted is set to True.
| int textPadding |
The padding space between text and Sprite's boundary, in pixels.
The default value is 0. Tip See Sprite Visual Anatomy
Note This property has no effect unless the property textFormatted is set to True.
| int textLineSpacing |
The line space of this Sprite, in pixels.
The default value is 0. Tip See Sprite Visual Anatomy
Note This property has no effect unless the property textFormatted is set to True.
| int textOffsetX |
The X-offset in pixels when the Sprite's text is rendered
The default value is 0. Tip See Sprite Visual Anatomy
| int textOffsetY |
The Y-offset in pixels when the Sprite's text is rendered
The default value is 0. Tip See Sprite Visual Anatomy
| bool useMonoFont |
Whether to use mono-spaced font when render the Sprite's text.
The default value is False, means use proportional font for Sprite's text. Tip See Sprite Visual Anatomy
| MiniAWT::Graphics::BitmapFont* bitmapFont |
The BitmapFont of this Sprite.
By default this property is NULL, indicates the Sprite does not have BitmapFont and the text is rendered by regular application font. Depends on another property useMonoFont, the render pipeline will use Application's proportional font or mono-spaced font (both can be retrieved by function MiniAWT::Application::getFont()) to render the Sprite's text.
When this property is set to a reference of a BitmapFont , the render pipeline use this special font to render Sprite's text. Usually the bitmap font assigned to a Sprite are artistic font and has strong decoration effect, suitable for applications like games.
Tip See Sprite Visual Anatomy
Note The "active" counterpart of this property is bitmapFontBright.
| MiniAWT::Graphics::BitmapFont* bitmapFontBright |
The BitmapFont of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ). See bitmapFont for more details.
The default value is NULL, indicates the Sprite does not have BitmapFont.
Tip See Sprite Visual Anatomy
| Texture* texture |
The Sprite's texture its graphical element rendered by a picture above the Sprite's background and underneath the Sprite's text. By default this property is NULL, indicates the Sprite does not have a texture.
When this property is set to a reference of a Texture , the render pipeline renders this texture right on top of its background. The most common use of Sprite's texture is to give it a pictorial presentation.
Tip See Sprite Visual Anatomy
Note The "active" counterpart of this property is textureBright.
| Texture* textureBright |
The Texture of this Sprite when it is under "active" state (The Sprite's state is STATE_ACTIVE ). See texture for more details. Tip See Sprite Visual Anatomy
| int textureTransparency |
The transparency level of the Sprite's texture, in range of [0, 255] where 0 indicates full opacity and 255 indicates full transparency.
The default value is 0.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| bool textureTiling |
Indicates whether the Texture of this Sprite should be rendered as a single picture or repeated as numbers of picture tiles.
When this property is set to True, then the texture will be used as "picture tiles" to fill up the whole area of the Sprite's bounding box. The tile size can be controlled by property textureOutputW and textureOutputH. The default value is False, rendered as a single picture.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int textureOutputW |
The width of Sprite's texture output size, in pixels.
The default value is -1, indicates the output size is not specified, in this case render pipeline render the texture with the same size of the Sprite's bounding box.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int textureOutputH |
The height of Sprite's texture output size, in pixels.
The default value is -1, indicates the output size is not specified, in this case render pipeline render the texture with the same size of the Sprite's bounding box.
Tip See Sprite Visual Anatomy
Note This property is used for both "normal" and "active" state.
| int textureOffsetX |
The horizontal offset when the Sprite's texture is rendered, in pixel.
The default value is 0. Tip See Sprite Visual Anatomy
| int textureOffsetY |
The vertical offset when the Sprite's texture is rendered, in pixel.
The default value is 0. Tip See Sprite Visual Anatomy
| int textureClipX |
The X coordinate of the left-top corner of texture's clipping window, defined in pixels in texture's Bitmap pixel space.
The properties textureClipX, textureClipY, textureClipW and textureClipH works together to define a clipping window of Sprite's texture. When the texture is rendered, only the portion in the clipping window is used. If any one of these four properties is set to -1, it indicates that there is no clipping window and the texture is rendered by its whole content. The default value is -1.
Tip See Sprite Visual Anatomy
Note The clipping window has dimension defined in texture's Bitmap pixel space.
| int textureClipY |
The Y coordinate of the left-top corner of texture's clipping window, defined in pixels in texture's Bitmap pixel space.
See textureClipX for more details about texture clipping window. The default value is -1.
Tip See Sprite Visual Anatomy
Note The clipping window has dimension defined in texture's Bitmap pixel space.
| int textureClipW |
The width of texture's clipping window, defined in pixels in texture's Bitmap pixel space.
See textureClipX for more details about texture clipping window. The default value is -1.
Tip See Sprite Visual Anatomy
Note The clipping window has dimension defined in texture's Bitmap pixel space.
| int textureClipH |
The height of texture's clipping window, defined in pixels in texture's Bitmap pixel space.
See textureClipX for more details about texture clipping window. Note The clipping window has dimension defined in texture's Bitmap pixel space. The default value is -1.
Tip See Sprite Visual Anatomy
Note The clipping window has dimension defined in texture's Bitmap pixel space.
| int textureAlignment |
The property determines how Sprite's texture is aligned with Sprite when it is rendered. The value must be one of constants defined in POSITION_ANCHORPOINT_TYPE.
Tip See Sprite Visual Anatomy
The default value is ANCHOR_LEFT_TOP, which means the texture is aligned to the left-top corner of Sprite's bounding box.
| float textureRotation |
The texture rotation angle, measured in degree and makes texture rotated counterclockwise.
The texture is rotated around the rotation anchor point, defined by textureRotationAnchorX and textureRotationAnchorY. textureRotationAnchorX and textureRotationAnchorY are two float numbers normalized by textureOutputW and textureOutputH, Following pseudo code shows the logic how render pipeline calculates the actual rotation pivot:
The default value of both textureRotationAnchorX and textureRotationAnchorY are set to 0, means the texture are rotated (if textureRotation is not 0) around its center. Tip See Sprite Visual Anatomy
| float textureRotationAnchorX |
Defines the horizontal offset of Sprite's texture rotation anchor (pivot), a floating-point number normalized by textureOutputW where 1.0f is equal to Sprite's texture output width. See textureRotation for more details.
Tip See Sprite Visual Anatomy
| float textureRotationAnchorY |
Defines the vertical offset of Sprite's texture rotation anchor (pivot), a floating-point number normalized by textureOutputH where 1.0f is equal to Sprite's texture output height. See textureRotation for more details.
Tip See Sprite Visual Anatomy
| int textureLeftEdgeInset |
One of four properties (textureLeftEdgeInset, textureRightEdgeInset, textureTopEdgeInset, textureBottomEdgeInset) who work together to define nine-patch sections of Sprite's texture so that the texture can be rendered in arbitrary aspect ratio without anamorphic effect.
Note The word "EdgeInset" is inspired by iOS imageEdgeInsets; the Android's equivalent technology is called NinePatch.
The value is defined in texture's Bitmap pixel space.
The default value of all of four properties are set to 0, means there is no edge insets applied. Tip See Sprite Visual Anatomy
| int textureRightEdgeInset |
One of four properties (textureLeftEdgeInset, textureRightEdgeInset, textureTopEdgeInset, textureBottomEdgeInset) who work together to define nine-patch sections of Sprite's texture so that the texture can be rendered in arbitrary aspect ratio without anamorphic effect.
See textureLeftEdgeInset for more details. Tip See Sprite Visual Anatomy
| int textureTopEdgeInset |
One of four properties (textureLeftEdgeInset, textureRightEdgeInset, textureTopEdgeInset, textureBottomEdgeInset) who work together to define nine-patch sections of Sprite's texture so that the texture can be rendered in arbitrary aspect ratio without anamorphic effect.
See textureLeftEdgeInset for more details. Tip See Sprite Visual Anatomy
| int textureBottomEdgeInset |
One of four properties (textureLeftEdgeInset, textureRightEdgeInset, textureTopEdgeInset, textureBottomEdgeInset) who work together to define nine-patch sections of Sprite's texture so that the texture can be rendered in arbitrary aspect ratio without anamorphic effect.
See textureLeftEdgeInset for more details. Tip See Sprite Visual Anatomy
| int guiType |
Sets or gets the GUI (graphical user interface) type of this Sprite, must be one of constants defined in GUI_SPRITE_TYPE.
Sprite's GUI type tells the role of a Sprite in user interface, see GUI_SPRITE_TYPE for more details. See Static Sprite vs Interactive Sprite for more details.
| bool tabStop |
Sets or gets whether this Sprite is a candidate for keyboard navigation (tab navigation mode).
When set to True, this Sprite can be reached by the keyboard navigation (tab navigation mode). The default value is True. When set to False, the navigation (tab navigation mode) focus will jump over this sprite and move to the next candidate.
| bool enabled |
Sets or gets whether this Sprite is enabled or disabled.
This property is only in use when the Sprite is an interactive sprite (see GUI_SPRITE_TYPE). The default value is True.
| int pickingExtensionX |
Sets or gets the horizontal picking extension of a interactive sprite (see GUI_SPRITE_TYPE), in pixels.
This property is used to enlarge (when value is positive) the "hot zone" of an interactive sprite to make picking it easier. The default value is 0 pixel. Tip See Sprite Visual Anatomy
| int pickingExtensionY |
Sets or gets the horizontal picking extension of a interactive sprite (see GUI_SPRITE_TYPE), in pixels.
This property is used to enlarge (when value is positive) the "hot zone" of an interactive sprite to make picking it easier. The default value is 0 pixel. Tip See Sprite Visual Anatomy
| bool draggable |
Sets or gets whether this Sprite is draggable, i.e., dragged by pointing device (mouse, touch, etc.).
| bool repeatMouseClicking |
Sets or gets whether this (interactive) Sprite is able to repeatedly generates clicking events when it is pressed by a pointing device (mouse, touch).
The default value is False, it means when this (interactive) Sprite is pressed by pointing device, it generates only one event MOUSE_STATUS_DOWN , and when it is released by pointing device, it generates another event MOUSE_STATUS_UP .
When this property is set to True, when this (interactive) Sprite is pressed by pointing device, it repeatedly generates event MOUSE_STATUS_DOWN and MOUSE_STATUS_UP until it is released by pointing device. As the result, the events generated between pointing device's press and release actions are in the following pattern:
The event simulation generates the effect that user repeatedly click this Sprite.
The following properties are used to do fine tune up on the simulated mouse clicking repeat:
| int clickingRepeatInterval |
The time interval in milliseconds that works together with repeatMouseClicking to control how fast the clicking events are repeated. See repeatMouseClicking for more details.
| int clickingRepeatFirstTimeInterval |
The time interval in milliseconds that works together with repeatMouseClicking to determine how much delay applied before the first clicking events repeat. See repeatMouseClicking for more details.
| bool persistent |
Sets or gets whether the value maintained by this (interactive) Sprite will be persistent across application sessions.
Certain types of interactive Sprite can maintain a value (see Sprites Maintains a Value). When this property is set to True, the value maintained by this Sprite will be automatically saved in Application's local storage when the OGCanvas who contains this Sprite unload its content (see GUI::OGCanvas::unloadTemplate). The value will be automatically recovered next time when OGCanvas load the same content (see GUI::OGCanvas::loadTemplate()). See OGCanvas for more details. This behavior generates an effect that this (interactive) Sprite is able to automatically persist the value it maintains.
OGTemplate has a special attribute persistent which indicate the value of the target Sprite and LWComponent should be persistent across multiple application sessions. For example, the value of edit-box (Sprite) that contains user name and e-mail, or the user selection of a drop-down box (LWComboBox) that contains the country/area might need to be persistent across application sessions for convenience purpose. This can be done easily by applying persistent attribute and set it to true.
During the application sessions, when user input text for user name and e-mail, or select the country from the drop-down list, the value will be persisted and during the next application sessions, the updated persisted value will be presented.
See OGTemplate reference for more details.
The default value is False.
| RenderListener* renderListener |
Sets or gets the RenderListener of this Sprite, see RenderListener for more tails.
The default value is NULL, means the listener is not registered.
| DraggingListener* draggingListener |
Sets or gets the DraggingListener of this Sprite, see DraggingListener for more tails.
The default value is NULL, means the listener is not registered.
| EditBoxVerificationListener* editBoxVerificationListener |
Sets or gets the EditBoxVerificationListener of this Sprite, see EditBoxVerificationListener for more tails.
The default value is NULL, means the listener is not registered.