Views
Foundation Package API Reference Guide
Product Documentation:
Views Documentation Home
Views Style Sheets Reference

Views Style Sheet Syntax

Customizing Padding, Margin and Borders with the Box Model

When styling Views gadgets, each gadget is comprised of four enclosed rectangles, the margin rectangle, the border rectangle, the padding rectangle and finally, the content rectangle. The four rectangles together make up the box model.

Each of the rectangles of the box model are styled with specific CSS attributes including defining the width and height of each of the rectangles. By default, the width and height of the margin, border and padding rectangles are zero.

In most cases the width and height of the gadget is set programmatically and is not controlled by CSS. Some free floating gadgets that are part of a parent gdget's bounding box allow changing the width and height of the gadget. The size of the inner content region is the space left over after defining the size of the margin, border, and padding for the gadget. This differs from the typical definition of width and height used by elements displayed by web browsers where the width and height of the component defines the size of the content region and the padding, border, and margin add to the width and height.

Margin Rectangle

The outermost rectangle of the box model is the margin. It provides a transparent space around the gadget. The default width of the margin is zero pixels but is overridden with the margin, margin-top, margin-right, margin-bottom and margin-left attributes. The following table summarizes the margin properties:

Property Description
margin Defines the gadget's margins. Equivalent to specifying margin-top, margin-right, margin-bottom, and margin-left.
margin-top Define the top margin.
margin-right Define the right margin.
margin-bottom Define the bottom margin.
margin-left Define the left margin.

Border Rectangle

The border rectangle is used to draw an optional border inside the margin rectangle but outside the padding rectangle of the gadget. By default, the thickness or width of the border is zero pixels but, as with margin, it is overridden with the border, border-top, border-right, border-bottom and border-left attributes. The width, color, line style and corner radius of the border are styled using the following attributes.

Property Description
border Defines the gadget's borders. Equivalent to specifying border-top, border-right, border-bottom, and border-left.
border-top Define the top border.
border-right Define the right border.
border-bottom Define the bottom border.
border-left Define the left border.

border-style dotted | dashed | solid | inset | outset | none | hidden

Sets the display style of the border for one to four values for each of the border edges (top border, right border, bottom border, left border).

border-color name | HEX | RGB

The border-color property is used to set the color of the four borders of a gadget. Colors can be set by a name, such as "red", HEX, a hexadecimal value such as #eeff00, an RGB value, such as rgb(238, 255, 0) or transparent. One to four values for each of the border edges (top border, right border, bottom border, left border) can be specified.

border(-top | -right | -bottom | -left) border-width border-style border-color

Shorthand border property that allows border width, style and color to be specified at one time. Use border-top, border-right, border-bottom and border-left to define a border style for a specific border edge.

border-radius

The border-radius property is used to add rounded corners to the gadget. One to four values for each of the border corners (top border, right border, bottom border, left border) can be specified. A border radius can only be applied to uniform borders that share the same color, width and only on solid, dotted and dashed line styles.

Padding Rectangle

The padding property is used to define space around the gadget's content and inside the border. As with margin, padding can be defined for each edge of the gadget or all of them at once. The default width of the padding is zero pixels but is overridden with the padding, padding-top, padding-right, padding-bottom and padding-left attributes. The following table summarizes the padding property:

Property Description
padding Defines the gadget's padding. Equivalent to specifying padding-top, padding-right, padding-bottom, and padding-left.
padding-top Define the top padding.
padding-right Define the right padding.
padding-bottom Define the bottom padding.
padding-left Define the left padding.

Content Rectangle

The content region of a gadget is the inner most rectangle. It is the region left after the space from the margin, border and padding have been subtracted from the overall width and height of the gadget. This definition of width and height of the content region is different from the traditional CSS definitions used by browsers where the width and height of the component defines the size of the content region.

IlvGadget CSS States

The following table summarizes the different states, represented through pseudo classes, that an IlvGadget can be in. The states are used in CSS selectors to define different styles based on the state of the gadget.

Selector IlvGadget Method Equivalent Comments
active Gadget CSS state is set "active" when button is down. There is no equivalent state in when done programmatically in Views. The state can be simulated with an additional property. See for instance IlvToggle::getStylableState() for more information.
checked IlvGadget::getState() Style "checked" is set to true when the gadget is checked.
enabled IlvGadget::isSensitive() Style "enabled" is set to true when the gadget is enabled.
focus IlvGadget::hasFocus() Style "focus" is set to true when the gadget has focus.
hover IlvGadget::isHighlighting() Style "hover" is set to true when the mouse or pointer hovers over the gadget.

NOTE: The CSS order is important when specifying multiple different styles with different CSS pseudo classes (states). They are equal in specificity so the order matters. State :active must be specified before :hover to make both rules work. For example, IlvButton during clicking has :active pseudo class, but since clicking involves hovering mouse pointer over the button it also has :hover state. If they are specified in the wrong order, :hover rule will override :active and any common style properties between the rules will be taken from :hover. This overriding behaviour comes from CSS standard but Views differs from standard because the order in which the rules must be specified is reversed.

IlvGadgetItem, IlvTreeGadgetItem, and IlvNotebookPageItem CSS States

IlvGadgetItem, IlvTreeGadgetItem, and IlvNotebookPageItem supports the following CSS states, represented through pseudo classes. The states are used in CSS selectors to define different styles based on the state of the gadget.

State IlvGadgetItem Method Equivalent
active IlvGadgetItem::isSelected()
enabled IlvGadgetItem::isSensitive()
focus IlvGadgetItem::isHighlighted()
hover

IlvMenuItem and IlvMenuItemPath CSS States

IlvMenuItem supports the following CSS states, represented through pseudo classes. The states are used in CSS selectors to define different styles based on the state of the gadget.

State IlvMenuItem Method Equivalent
active IlvMenuItem::isSelected()
enabled IlvMenuItem::isSensitive()
focus
hover IlvMenuItem::isHighlighted()

List of Views CSS Properties

The following CSS properties are supported by all Views gadgets:

Property Description
background Shorthand property for setting the background color, image, repeat, and/or position properties. Example: IlvButton { background: blue }
background-color Defines the background color used for the gadget. Example: IlvButton { background-color: red }
background-image Defines the background image used for the gadget. Example: IlvButton { background-image: url(images/logo.png) }
background-size Specifies the horizontal and vertical size of the background image. Valid values include "auto" and in pixels. Example: IlvButton { background-image: url(images/logo.png); background-size: 50px 50px; }
background-position Specifies the horizontal and vertical starting position of the background image for the gadget. Valid alignment values for the horizontal and/or vertical alignment are: top, bottom, left, right, center. The default property setting is top left. Example: IlvButton { background-image: url(images/logo.png); background-position: bottom right; }
border Shorthand property for setting the gadgets border. Combines using border-color, border-style, and/or border-width properties into one form. Example: IlvButton { border: 1px solid blue }
border-top Shorthand property for setting the top border color, style, and/or width. Example: IlvButton { border-top: 1px solid blue }
border-right Shorthand property for setting the right border color, style, and/or width. Example: IlvButton { border-right: 1px solid blue }
border-bottom Shorthand property for setting the bottom border color, style, and/or width. Example: IlvButton { border-bottom: 1px solid blue }
border-left Shorthand property for setting the left border color, style, and/or width. Example: IlvButton { border-left: 1px solid blue }
border-color Define the color of all the border's edges. Example: IlvButton { border-color: blue }
border-radius Defines the radius of the border's corners. The border-radius clips the background of the gadget. Only dashed, dotted, and solid border styles are supported when using a border radius. Unsupported styles revert to a solid border. Example: IlvButton { border-radius: 5px }
border-style Defines the style of the border to use for the gadget. Supported border styles include: dashed, dotted, inset, outset, solid, hidden, inherit, none. Example: IlvButton { border-style: dashed }
border-width Defines the width of the border in pixels, e.g. IlvButton { border-width: 2px }. Individual border edge widths are set with border-top, border-right, border-bottom, and border-left.
caret-color Shorthand for setting the color of the cursor/caret for text gadgets. Example: IlvText, IlvTextField > Text { caret-color: blue }
color Shorthand for setting the text-color for the gadget. Example: IlvButton { color: blue }
margin Shorthand property to defines the margin for all four sides of the gadget. It is equivalent to setting the top, right, bottom, and left margin. Set margin to 5 pixel example: IlvButton { margin: 5px } Set top bottom margin to 5 pixels and left and right margin to 10 pixels example: IlvButton { margin: 5px 10px } Set top, right, bottom, and left margin: IlvButton { margin: 1px 2px 3px 4px }
margin-top Sets the top margin for the gadget. Example: IlvButton { margin-top: 5px }
margin-right Sets the right margin for the gadget. Example: IlvButton { margin-right: 5px }
margin-bottom Sets the bottom margin for the gadget. Example: IlvButton { margin-bottom: 5px }
margin-left Sets the left margin for the gadget. Example: IlvButton { margin-left: 5px }
opacity Sets the opacity level of the gadget. Example: IlvButton { opacity: .5 }
padding Shorthand property to defines the padding for all four sides of the gadget. It is equivalent to setting the top, right, bottom, and left padding. Set padding to 5 pixel example: IlvButton { padding: 5px } Set top bottom padding to 5 pixels and left and right padding to 10 pixels example: IlvButton { padding: 5px 10px } Set top, right, bottom, and left padding: IlvButton { padding: 1px 2px 3px 4px }
padding-top Sets the top padding for the gadget. Example: IlvButton { padding-top: 5px }
padding-right Sets the right padding for the gadget. Example: IlvButton { padding-right: 5px }
padding-bottom Sets the bottom padding for the gadget. Example: IlvButton { padding-bottom: 5px }
padding-left Sets the left padding for the gadget. Example: IlvButton { padding-left: 5px }
text-align Sets the text alignment for the gadget. Accepted alignments include: left, center, right, start, end, initial, inherit. Alignment depends on the alignment mode set in Views, RightToLeft or LeftToRight. Example: IlvButton { text-align: center }

Styling Gadgets with CSS Look and Feel versus Traditional Gadget Styling

Views developers using the new CSS styling capabilities introduced in Views 7.0, should use the IlvStylable inteface, accessed through the IlvGadget::style() method to define a gadgets look and feel. If not using CSS Look and Feel, developers should use the traditional IlvPalette method for assigning style properties. The following provides an example of using the traditional gadget look and feel methods to define the style versus using CSS Look and Feel and style().

The following code snippets show getting and setting of gadgets properties using traditional styling capabilities:

// Get the background color for the toolbar
auto* oldColor = toolBar->getBackground();
// Set the background color to red on the toolbar
toolBar->setBackground(display->getColor("red"));
// Get the horizontal and vertical margin for the toolbar
auto marginH = toolBar->getHMargin();
auto marginV = toolBar->getVMargin();
// Get the font for the toolbar
auto* font = toolBar->getPalette()->getFont();

When using CSS Look and Feel, the style() method is used to get and set the gadget's CSS properties:

// Get the background color for the toolbar
auto* oldCssColor = toolBar->style().getBackgroundColor();
// Set the background color to red on the toolbar
toolBar->style().setBackgroundColor(display->getColor("blue"));
// Get the horizontal and vertical margin for the toolbar
auto marginHCss = toolBar->style().getMargin(IlvHorizontal);
auto marginVCss = toolBar->style().getMargin(IlvVertical);
// Get the font for the toolbar
auto* cssFont = toolBar->style().getFont();

Limitations

The Views CSS styling capabilities currently have some limitations:

  • Dataccess gadgets are not supported
  • Prototypes have limited support for CSS styling

« Views Style Sheet Syntax Views Style Sheets Examples »

IlvDisplay::getColor
IlvColor * getColor(const char *name, IlBoolean isMutable=IlFalse)
Gets a color by name.