openGear Style Hints
openGear Style Hints provide something similar to an inline style CSS attribute in HTML. For certain components, they can be used to specify a background color, foreground color, border, and icon. The hints can be provided inside OGLML tags or via parameter choice constraint values.
Syntax
To specify a style hint inside an OGLML tag, the style attribute is used:
<component style="style-hint;style-hint;...;" component attributes>
To specify a style hint within a parameter choice constraint, the style tag is inserted at the end of the constraint value, enclosed in angle brackets (< >). In order to represent the angle brackets in the OGLML document, they must use standard XML escape sequences (< >). Specifying hints within the constraint value allows different styles to be applied to each choice.
<constraint key="key">value<style-tag;style-tag;... ></constraint>
Note Style hints may be specified in either the OGLML style attribute or within the constraint value, but not both.
For clarity, this document will provide examples using the OGLML style attribute only, however the style hints may be utilized within constraints unless specifically mentioned.
Style Hint Reference
The following style hints are supported:
Tag |
Description |
Sets the component background color. |
|
Sets the component border style. |
|
Sets the component border color. |
|
Sets the component background color. |
|
Sets the alignment of a background image. |
|
Controls how a background image is sized. |
|
Sets a container background to image located at a specified URL. |
|
Removes a component drag icon. |
|
Sets a component drag icon to image encapsulated in an external OID. |
|
Sets a component drag icon to image located at a specified URL. |
|
Style modifier when button value is false. |
|
Sets the component foreground color. |
|
Sets the font type. |
|
Sets the table gridline color. |
|
Removes a component hover icon. |
|
Sets a component hover icon to image encapsulated in an external OID. |
|
Sets a component hover icon to image located at a specified URL. |
|
Removes a component icon. |
|
Sets a component icon to image encapsulated in an external OID. |
|
Sets a component icon to image located at a specified URL. |
|
Sets insets around the label of a button. |
|
Sets the text outline color. |
|
Sets the text font size. |
|
Applies style hints defined within a style tag. |
|
Style modifier when button value is true. |
|
Sets a tooltip for a label or button. |
|
Sets the alignment of text. |
User styles may be created within an OGLML document to allow standardized formatting to be applied to multiple components. Styles are defined using the style tag. A predefined style may be referenced by a component as part of its style attribute. Additional style hints may be included in the same style attribute string. If the style string explicitly specifies a hint which contradicts a hint in the predfined style, the explicitly added hint shall supersede.
Style Hint |
Values |
Restrictions |
Description |
style:style-id |
String |
The style with the provided ID must be defined in an OGLML document at a higher scope than where it is referenced. |
Apply the style hints of the style defined in a different set of style hints. See style tag documentation for more information. |
Examples
The following example applies button style hints as defined in the predefined style CommandButtonStyle. Note that the “Stop” button has an additional hint applied (size:big), and overrides the background color (bg#ff0000).
<style id="ButtonStyle" value="bg#808000;bdr:etched;"/>
<button name="Start" style="style:ButtonStyle;"/>
<button name="Stop" style="style:ButtonStyle;size:big;bg#ff0000;"/>
<button name="Reset" style="style:ButtonStyle;"/>
Figure 60 - Style Tag Example
The foreground, background and border colors of components may be specified. It is often a good idea to override the background and foreground as a pair to avoid the possibility of the background and foreground being the same (or similar) colors in the UI.
Style Hint |
Values |
Restrictions |
Description |
#color-value or bg#color-value |
#RRGGBB or #color-constant or #RRGGBBAA |
|
Set the background color of the component. Colors may be specified as RGB, RGBA or one of the pre-defined color constants. R, G, B and A are specified as 2-digit hex values. |
fg#color-value
|
#RRGGBB or #color-constant or #RRGGBBAA |
|
Set the foreground color of the component. Colors may be specified as RGB, RGBA or one of the pre-defined color constants. R, G, B and A are specified as 2-digit hex values. |
bdr#color-value |
#RRGGBB or #color-constant or #RRGGBBAA |
|
Create a line border around the component with the specified color. Colors may be specified as RGB, RGBA or one of the pre-defined color constants. R, G, B and A are specified as 2-digit hex values. |
o#color-value |
#RRGGBB or #color-constant or #RRGGBBAA |
|
Create an outline around the text within a component with the specified color. Colors may be specified as RGB, RGBA or one of the pre-defined color constants. R, G, B and A are specified as 2-digit hex values. |
grid#color-value |
#RRGGBB or #color-constant or #RRGGBBAA |
Applies to table container only. |
Specifies the color of the gridlines for a table container. Colors may be specified as RGB, RGBA or one of the pre-defined color constants. R, G, B and A are specified as 2-digit hex values. |
Example
The following style tag creates a label using the predefined background #panelbg and the foreground (text) in orange.
<label name="Label" style="bg#panelbg;fg#FFC000;"/>
DashBoard defines the following color constants, which make up the standard color scheme. These colors are used in the standard controls within DashBoard, but may be applied to the background, foreground or border color style tag of any component. Custom color constants may be defined within an OGLML document using the color tag.
Color Constant |
Description |
#control |
The background color of a basic control or panel. |
#dark |
The dark panel background color used in the default DashBoard display. |
#foreground |
The foreground color of a basic control or button. |
#listbg |
The default background color of a combo box control. |
#listfg |
The default foreground color of a combo box control. |
#panelfg |
The proper foreground color to use on a panel. |
#panelbg |
The standard panel background color used in the default DashBoard display. |
#readonlybg |
The default background color of a read-only text box. |
#readonlyfg |
The default foreground color of a read-only text box. |
#selectbg |
The default background color for a selected toggle button. |
#selectfg |
The default foreground color for a selected toggle button. |
#tabbg |
The default background color of a selected tab. |
#tabfg |
The default foreground color of a selected tab. |
#textbg |
The default background color of a read/write text box. |
#textfg |
The default foreground color of a read/write text box. |
#transparent |
No fill; the element will be transparent. |
#user-defined-color |
User defined color. Defined using the color tag. |
Examples
The following image illustrates the pre-defined color constants, as rendered in DashBoard 7.
Figure 61 - Predefined color constants
The style of a component border may be specified with the bdr hint. If the border hint is not specified, a simple line will be drawn for the control border.
Note: The containertype attribute, if specified for a component, will override the bdr style hint.
Style Hint |
Values |
Restrictions |
Description |
bdr:border-style |
none |
|
Removes the border from the component. |
etched |
Create an etched border around the component. |
||
shadow |
Creates a drop shadow under the component. |
||
bdr#color-value |
Sets border color; see Component Color Section. |
||
grid#color-value |
Sets grid color in a table; see Component Color Section. |
Examples
The following image illustrates the border style hint:
Figure 62 - Border style
The following style hints modify the rendering of text in a component.
Style Hint |
Values |
Restrictions |
Description |
size:font-size |
Integer size smaller small normal big bigger biggest |
|
Set the font size for the component. Number specifies a font size in points (1/72”). smaller corresponds to 2/3 normal size. biggest corresponds to 4x normal size. See examples below. |
font:font-type |
default bold mono |
|
Set the control font to the default font, a bold font, or a mono-spaced font. |
txt-align:alignment |
center north northeast east southeast south southwest west northwest |
|
Controls the position of text within a button or label control. |
fg#color-value |
Sets text foreground color; see Component Color Section. |
||
o#color-value |
Sets text outline color; see Component Color Section. |
Examples
The following image illustrates the size style
Figure 63 - size style attribute
The following image illustrates the font style:
Figure 64 - font style attribute
Icon styles may be applied to label and button components. DashBoard allows separate icons to be defined for the default icon, the icon when a mouse hovers over the control, and the icon when the control is dragged (if dragging is enabled on the component).
Note Icon Styles have no effect on buttons with the flat attribute.
Style Hint |
Values |
Restrictions |
Description |
i-eo:external-oid
|
External OID |
External OID specified must be type 0x03. |
Set the icon for the component (applies to labels and buttons). |
i-u: image-URL |
URL String |
Full qualified URL to PNG, GIF or JPG image. |
Set the icon for the component. (applies to labels and buttons) |
i:none |
|
|
Remove the icon for the component. |
di-eo:external-oid
|
External OID |
External OID specified must be type 0x03. |
Set the drag icon for the component (only applies if “dragvalue” attribute is used). |
di-u:image-URL |
URL String |
Full qualified URL to PNG, GIF or JPG image. |
Set the drag icon for the component (only applies if “dragvalue” attribute is used) |
di:none |
|
|
Remove the drag icon for the component. |
hi-eo:external-oid
|
External OID |
External OID specified must be type 0x03. |
Set the hover icon for the component (applies to buttons) |
hi-u: image-URL |
URL String |
Full qualified URL to PNG, GIF or JPG image. |
Set the hover icon for the component (applies to buttons) |
hi:none |
|
|
Remove the hover icon for the component. |
<button buttontype="push" style="i-u:http://my-server/RossLogo.jpg;hi-u:http://my-server/DashBoardLogo.jpg;" />
Figure 65 – Background and Hover Icon
Tooltip Style
Tooltip may be added to components. Balloon help text will be displayed when the mouse hovers over the component.
Style Hint |
Values |
Restrictions |
Description |
tt:tool-tip-string |
String |
May only be applied to label and buttons. |
Set the tooltip of the component to the specified String. A “;” can be inserted into the string by inserting the escape sequence “\;”. |
<button name="Tooltip" style="tt:This is the tooltip text" />
Figure 66 – Tooltip Style
Inset Style
Insets provide a margin from the edge of a component to the text or icon content.
Style Hint |
Values |
Restrictions |
Description |
m:top,left,bottom, |
4 Integers |
This hint can only be applied to button widgets. |
Sets the margins around the label of the button. The margins are specified in pixels. |
Background styles allow images to be placed in the background of container components.
Style Hint |
Values |
Restrictions |
Description |
b-u:image-url |
URL String |
Must be a fully qualified URL. |
Set the background image of the component. |
bg-fill:value |
none |
|
Do not scale the image. |
both |
|
Stretch the image to the width/height of the control. |
|
horizontal |
|
Scale the image to the width of the control (maintain aspect ratio). |
|
vertical |
|
Scale the image to the height of the control (maintain aspect ratio). |
|
fit |
|
Scale the image to the largest size that will fit inside of the control (maintain aspect ratio). |
|
crop |
|
Scale the image to fill the control maintaining the aspect ratio. Crop the image to remove the parts that don’t fit. |
|
tile |
|
Tile the image (starting at the upper left) to fill the background of the control. |
|
paint9 |
|
Divide the image into 9 areas (defined with Background Insets) to define fixed corners, vertically or horizontally stretched sides, and a stretched center. |
|
bg-align:value |
center north northeast east southeast south southwest west northwest |
|
If the fill is set to anything other than “both” or “tile”, this controls where the background is positioned in the component. |
All style options can be overridden for toggle and radio buttons, such that the style of the widget is determined by the value of the backing parameter. For toggle buttons, the style can be specified for the true state (button toggled down) and false state (button toggled up). For radio buttons, the style can be specified for each choice for the true state (choice selected) and false state (choice not selected).
Syntax
<component style="t:true-style-hint;f:false-style-hint;...;" >
Hint Modifier |
Values |
Restrictions |
Description |
t:true-style-hint |
Valid style hint |
|
Applies the style hint only when the choice is true. |
f:false-style-hint |
Valid style hint |
|
Applies the style hint only when the choice is false. |
Examples
The following example creates a toggle button whose color is green when true (toggled down) and red when false (toggled up):
<param oid="0x7" style="t:bg#00ff00;f:bg#ff0000;" widget="13"/>
Figure 67 - Toggle Button Style Modifier
The following example changes the font size to big for the selected radio button:
<param oid="0x6" style="t:size:big;f:size:normal;" widget="9"/>
Figure 68 – Radio Button Style Modifier