brl/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

StThemeNode: simplify use of get_color/get_double/get_length

Browse Source 
Although within St itself there are situations where the semantics of
these functions (return TRUE or FALSE and return the actual value in
an out parameter) is useful, it's mostly just annoying at the
application level, where you generally know that the CSS property is
going to specified, and there is no especially sane fallback if it's
not.

So rename the current methods to lookup_color, lookup_double, and
lookup_length, and add new get_color, get_double, and get_length
methods that don't take an "inherit" parameter, and return their
values directly. (Well, except for get_color, due to the lack of (out
caller-allocates) in gjs.)

And update the code to use either the old or new methods as appropriate.

https://bugzilla.gnome.org/show_bug.cgi?id=632590
This commit is contained in:
Dan Winship 2010-09-26 17:38:36 -04:00
parent 85d3336245
commit 8886b7433c
16 changed files with 185 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
js/ui/altTab.js
View File

@ -102,9 +102,7 @@ AltTabPopup.prototype = {
childBox.x1 = Math.max(primary.x + leftPadding, childBox.x1 - offset - hPadding);
}
let [found, spacing] = this.actor.get_theme_node().get_length('spacing', false);
if (!found)
spacing = 0;
let spacing = this.actor.get_theme_node().get_length('spacing');
childBox.x2 = childBox.x1 + childNaturalWidth;
if (childBox.x2 > primary.x + primary.width - rightPadding)
@ -501,8 +499,7 @@ SwitcherList.prototype = {
this._list = new Shell.GenericContainer({ style_class: 'switcher-list-item-container' });
this._list.spacing = 0;
this._list.connect('style-changed', Lang.bind(this, function() {
let [found, spacing] = this._list.get_theme_node().get_length('spacing', false);
this._list.spacing = (found) ? spacing : 0;
this._list.spacing = this._list.get_theme_node().get_length('spacing');
}));
this._list.connect('get-preferred-width', Lang.bind(this, this._getPreferredWidth));
@ -1035,9 +1032,7 @@ ThumbnailList.prototype = {
let totalPadding = this._items[0].get_theme_node().get_horizontal_padding() + this._items[0].get_theme_node().get_vertical_padding();
totalPadding += this.actor.get_theme_node().get_horizontal_padding() + this.actor.get_theme_node().get_vertical_padding();
let [labelMinHeight, labelNaturalHeight] = this._labels[0].get_preferred_height(-1);
let [found, spacing] = this._items[0].child.get_theme_node().get_length('spacing', false);
if (!found)
spacing = 0;
let spacing = this._items[0].child.get_theme_node().get_length('spacing');
availHeight = Math.min(availHeight - labelNaturalHeight - totalPadding - spacing, THUMBNAIL_DEFAULT_SIZE);
let binHeight = availHeight + this._items[0].get_theme_node().get_vertical_padding() + this.actor.get_theme_node().get_vertical_padding() - spacing;

31
js/ui/boxpointer.js
View File

@ -46,9 +46,7 @@ BoxPointer.prototype = {
let x = this.actor.x;
let y = this.actor.y;
let themeNode = this.actor.get_theme_node();
let [found, rise] = themeNode.get_length('-arrow-rise', false);
if (!found)
rise = 0;
let rise = themeNode.get_length('-arrow-rise');
this.actor.opacity = 0;
this.actor.show();
@ -82,9 +80,7 @@ BoxPointer.prototype = {
let originalX = this.actor.x;
let originalY = this.actor.y;
let themeNode = this.actor.get_theme_node();
let [found, rise] = themeNode.get_length('-arrow-rise', false);
if (!found)
rise = 0;
let rise = themeNode.get_length('-arrow-rise');
switch (this._arrowSide) {
case St.Side.TOP:
@ -118,13 +114,12 @@ BoxPointer.prototype = {
_adjustAllocationForArrow: function(isWidth, alloc) {
let themeNode = this.actor.get_theme_node();
let found, borderWidth, base, rise;
[found, borderWidth] = themeNode.get_length('-arrow-border-width', false);
let borderWidth = themeNode.get_length('-arrow-border-width');
alloc.min_size += borderWidth * 2;
alloc.natural_size += borderWidth * 2;
if ((!isWidth && (this._arrowSide == St.Side.TOP || this._arrowSide == St.Side.BOTTOM))
|| (isWidth && (this._arrowSide == St.Side.LEFT || this._arrowSide == St.Side.RIGHT))) {
let [found, rise] = themeNode.get_length('-arrow-rise', false);
let rise = themeNode.get_length('-arrow-rise');
alloc.min_size += rise;
alloc.natural_size += rise;
}
@ -146,9 +141,8 @@ BoxPointer.prototype = {
_allocate: function(actor, box, flags) {
let themeNode = this.actor.get_theme_node();
let found, borderWidth, borderRadius, rise, base;
[found, borderWidth] = themeNode.get_length('-arrow-border-width', false);
[found, rise] = themeNode.get_length('-arrow-rise', false);
let borderWidth = themeNode.get_length('-arrow-border-width');
let rise = themeNode.get_length('-arrow-rise');
let childBox = new Clutter.ActorBox();
let availWidth = box.x2 - box.x1;
let availHeight = box.y2 - box.y1;
@ -183,19 +177,18 @@ BoxPointer.prototype = {
_drawBorder: function(area) {
let themeNode = this.actor.get_theme_node();
let found, borderWidth, borderRadius, rise, base;
[found, borderWidth] = themeNode.get_length('-arrow-border-width', false);
[found, base] = themeNode.get_length('-arrow-base', false);
[found, rise] = themeNode.get_length('-arrow-rise', false);
[found, borderRadius] = themeNode.get_length('-arrow-border-radius', false);
let borderWidth = themeNode.get_length('-arrow-border-width');
let base = themeNode.get_length('-arrow-base');
let rise = themeNode.get_length('-arrow-rise');
let borderRadius = themeNode.get_length('-arrow-border-radius');
let halfBorder = borderWidth / 2;
let halfBase = Math.floor(base/2);
let borderColor = new Clutter.Color();
themeNode.get_color('-arrow-border-color', false, borderColor);
themeNode.get_color('-arrow-border-color', borderColor);
let backgroundColor = new Clutter.Color();
themeNode.get_color('-arrow-background-color', false, backgroundColor);
themeNode.get_color('-arrow-background-color', backgroundColor);
let [width, height] = area.get_surface_size();
let [boxWidth, boxHeight] = [width, height];

18
js/ui/iconGrid.js
View File

@ -113,18 +113,14 @@ BaseIcon.prototype = {
},
_onStyleChanged: function() {
let success, len;
let node = this.actor.get_theme_node();
[success, len] = node.get_length('spacing', false);
if (success)
this._spacing = spacing;
this._spacing = node.get_length('spacing');
if (this._setSizeManually)
return;
[success, len] = node.get_length('icon-size', false);
if (success)
let len = node.get_length('icon-size');
if (len > 0)
this._setIconSize(len);
}
};
@ -269,12 +265,8 @@ IconGrid.prototype = {
_onStyleChanged: function() {
let themeNode = this.actor.get_theme_node();
let [success, len] = themeNode.get_length('spacing', false);
if (success)
this._spacing = len;
[success, len] = themeNode.get_length('-shell-grid-item-size', false);
if (success)
this._item_size = len;
this._spacing = themeNode.get_length('spacing');
this._item_size = themeNode.get_length('-shell-grid-item-size');
this._grid.queue_relayout();
},

3
js/ui/messageTray.js
View File

@ -360,8 +360,7 @@ Notification.prototype = {
},
_styleChanged: function() {
let [hasSpacing, spacing] = this.actor.get_theme_node().get_length('spacing-columns', false);
this._spacing = hasSpacing ? spacing : 0;
this._spacing = this.actor.get_theme_node().get_length('spacing-columns');
},
_bannerBoxGetPreferredWidth: function(actor, forHeight, alloc) {

25
js/ui/popupMenu.js
View File

@ -143,13 +143,12 @@ PopupSeparatorMenuItem.prototype = {
let cr = area.get_context();
let themeNode = area.get_theme_node();
let [width, height] = area.get_surface_size();
let found, margin, gradientHeight;
[found, margin] = themeNode.get_length('-margin-horizontal', false);
[found, gradientHeight] = themeNode.get_length('-gradient-height', false);
let margin = themeNode.get_length('-margin-horizontal');
let gradientHeight = themeNode.get_length('-gradient-height');
let startColor = new Clutter.Color();
themeNode.get_color('-gradient-start', false, startColor);
themeNode.get_color('-gradient-start', startColor);
let endColor = new Clutter.Color();
themeNode.get_color('-gradient-end', false, endColor);
themeNode.get_color('-gradient-end', endColor);
let gradientWidth = (width - margin * 2);
let gradientOffset = (height - gradientHeight) / 2;
@ -200,20 +199,17 @@ PopupSliderMenuItem.prototype = {
let themeNode = area.get_theme_node();
let [width, height] = area.get_surface_size();
let found, handleRadius;
[found, handleRadius] = themeNode.get_length('-slider-handle-radius', false);
let handleRadius = themeNode.get_length('-slider-handle-radius');
let sliderWidth = width - 2 * handleRadius;
let sliderHeight;
[found, sliderHeight] = themeNode.get_length('-slider-height', false);
let sliderHeight = themeNode.get_length('-slider-height');
let sliderBorderWidth;
[found, sliderBorderWidth] = themeNode.get_length('-slider-border-width', false);
let sliderBorderWidth = themeNode.get_length('-slider-border-width');
let sliderBorderColor = new Clutter.Color();
themeNode.get_color('-slider-border-color', false, sliderBorderColor);
themeNode.get_color('-slider-border-color', sliderBorderColor);
let sliderColor = new Clutter.Color();
themeNode.get_color('-slider-background-color', false, sliderColor);
themeNode.get_color('-slider-background-color', sliderColor);
cr.setSourceRGBA (
sliderColor.red / 255,
@ -288,8 +284,7 @@ PopupSliderMenuItem.prototype = {
relY = absY - sliderY;
let width = this._slider.width;
let found, handleRadius;
[found, handleRadius] = this._slider.get_theme_node().get_length('-slider-handle-radius', false);
let handleRadius = this._slider.get_theme_node().get_length('-slider-handle-radius');
let newvalue;
if (relX < handleRadius)

12
js/ui/workspace.js
View File

@ -553,18 +553,10 @@ WindowOverlay.prototype = {
_onStyleChanged: function() {
let titleNode = this.title.get_theme_node();
let [success, len] = titleNode.get_length('-shell-caption-spacing',
false);
if (success)
this.title._spacing = len;
this.title._spacing = titleNode.get_length('-shell-caption-spacing');
let closeNode = this.closeButton.get_theme_node();
[success, len] = closeNode.get_length('-shell-close-overlap',
false);
if (success)
this.closeButton._overlap = len;
this.closeButton._overlap = closeNode.get_length('-shell-close-overlap');
this._parentActor.queue_relayout();
}

3
js/ui/workspaceSwitcherPopup.js
View File

@ -33,8 +33,7 @@ WorkspaceSwitcherPopup.prototype = {
this._list = new Shell.GenericContainer({ style_class: 'workspace-switcher' });
this._itemSpacing = 0;
this._list.connect('style-changed', Lang.bind(this, function() {
let [found, spacing] = this._list.get_theme_node().get_length('spacing', false);
this._itemSpacing = (found) ? spacing : 0;
this._itemSpacing = this._list.get_theme_node().get_length('spacing');
}));
this._list.connect('get-preferred-width', Lang.bind(this, this._getPreferredWidth));

5
js/ui/workspacesView.js
View File

@ -43,8 +43,7 @@ GenericWorkspacesView.prototype = {
this.actor.connect('style-changed', Lang.bind(this,
function() {
let node = this.actor.get_theme_node();
let [a, spacing] = node.get_length('spacing', false);
this._spacing = spacing;
this._spacing = node.get_length('spacing');
if (Main.overview.animationInProgress)
this._computeWorkspacePositions();
else
@ -609,7 +608,7 @@ WorkspaceIndicator.prototype = {
this._indicatorsPanel.add_actor(actor);
let [a, spacing] = actor.get_theme_node().get_length('border-spacing', false);
let spacing = actor.get_theme_node().get_length('border-spacing');
actor.x = spacing * i + actor.width * i;
},

4
src/st/st-box-layout.c
View File

@ -1018,9 +1018,9 @@ st_box_layout_style_changed (StWidget *self)
StBoxLayoutPrivate *priv = ST_BOX_LAYOUT (self)->priv;
StThemeNode *theme_node = st_widget_get_theme_node (self);
int old_spacing = priv->spacing;
double spacing = 0;
double spacing;
st_theme_node_get_length (theme_node, "spacing", FALSE, &spacing);
spacing = st_theme_node_get_length (theme_node, "spacing");
priv->spacing = (int)(spacing + 0.5);
if (priv->spacing != old_spacing)
clutter_actor_queue_relayout (CLUTTER_ACTOR (self));

2
src/st/st-button.c
View File

@ -109,7 +109,7 @@ st_button_style_changed (StWidget *widget)
ST_WIDGET_CLASS (st_button_parent_class)->style_changed (widget);
spacing = 6;
st_theme_node_get_length (theme_node, "border-spacing", FALSE, &spacing);
st_theme_node_lookup_length (theme_node, "border-spacing", FALSE, &spacing);
priv->spacing = (int)(0.5 + spacing);
/* update the label styling */

6
src/st/st-entry.c
View File

@ -202,13 +202,13 @@ st_entry_style_changed (StWidget *self)
st_theme_node_get_foreground_color (theme_node, &color);
clutter_text_set_color (CLUTTER_TEXT (priv->entry), &color);
if (st_theme_node_get_length (theme_node, "caret-size", FALSE, &size))
if (st_theme_node_lookup_length (theme_node, "caret-size", FALSE, &size))
clutter_text_set_cursor_size (CLUTTER_TEXT (priv->entry), (int)(.5 + size));
if (st_theme_node_get_color (theme_node, "caret-color", FALSE, &color))
if (st_theme_node_lookup_color (theme_node, "caret-color", FALSE, &color))
clutter_text_set_cursor_color (CLUTTER_TEXT (priv->entry), &color);
if (st_theme_node_get_color (theme_node, "selection-background-color", FALSE, &color))
if (st_theme_node_lookup_color (theme_node, "selection-background-color", FALSE, &color))
clutter_text_set_selection_color (CLUTTER_TEXT (priv->entry), &color);
font = st_theme_node_get_font (theme_node);

4
src/st/st-overflow-box.c
View File

@ -369,9 +369,9 @@ st_overflow_box_style_changed (StWidget *self)
StOverflowBoxPrivate *priv = ST_OVERFLOW_BOX (self)->priv;
StThemeNode *theme_node = st_widget_get_theme_node (self);
int old_spacing = priv->spacing;
double spacing = 0;
double spacing;
st_theme_node_get_length (theme_node, "spacing", FALSE, &spacing);
spacing = st_theme_node_get_length (theme_node, "spacing");
priv->spacing = (int)(spacing + 0.5);
if (priv->spacing != old_spacing)
clutter_actor_queue_relayout (CLUTTER_ACTOR (self));

4
src/st/st-scroll-bar.c
View File

@ -410,9 +410,9 @@ scroll_bar_allocate_children (StScrollBar *bar,
increment = page_size / (upper - lower);
min_size = 32.;
st_theme_node_get_length (theme_node, "min-size", FALSE, &min_size);
st_theme_node_lookup_length (theme_node, "min-size", FALSE, &min_size);
max_size = G_MAXINT16;
st_theme_node_get_length (theme_node, "max-size", FALSE, &max_size);
st_theme_node_lookup_length (theme_node, "max-size", FALSE, &max_size);
if (upper - lower - page_size <= 0)
position = 0;

6
src/st/st-table.c
View File

@ -988,11 +988,11 @@ st_table_style_changed (StWidget *self)
StThemeNode *theme_node = st_widget_get_theme_node (self);
int old_row_spacing = priv->row_spacing;
int old_col_spacing = priv->col_spacing;
double row_spacing = 0., col_spacing = 0.;
double row_spacing, col_spacing;
st_theme_node_get_length (theme_node, "spacing-rows", FALSE, &row_spacing);
row_spacing = st_theme_node_get_length (theme_node, "spacing-rows");
priv->row_spacing = (int)(row_spacing + 0.5);
st_theme_node_get_length (theme_node, "spacing-columns", FALSE, &col_spacing);
col_spacing = st_theme_node_get_length (theme_node, "spacing-columns");
priv->col_spacing = (int)(col_spacing + 0.5);
if (priv->row_spacing != old_row_spacing ||

136
src/st/st-theme-node.c
View File

@ -490,7 +490,7 @@ get_color_from_term (StThemeNode *node,
}
/**
* st_theme_node_get_color:
* st_theme_node_lookup_color:
* @node: a #StThemeNode
* @property_name: The name of the color property
* @inherit: if %TRUE, if a value is not found for the property on the
@ -507,14 +507,16 @@ get_color_from_term (StThemeNode *node,
* should be used instead. They are cached, so more efficient, and have
* handling for shortcut properties and other details of CSS.
*
* See also st_theme_node_get_color(), which provides a simpler API.
*
* Return value: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
st_theme_node_get_color (StThemeNode *node,
const char *property_name,
gboolean inherit,
ClutterColor *color)
st_theme_node_lookup_color (StThemeNode *node,
const char *property_name,
gboolean inherit,
ClutterColor *color)
{
int i;
@ -535,7 +537,7 @@ st_theme_node_get_color (StThemeNode *node,
else if (result == VALUE_INHERIT)
{
if (node->parent_node)
return st_theme_node_get_color (node->parent_node, property_name, inherit, color);
return st_theme_node_lookup_color (node->parent_node, property_name, inherit, color);
else
break;
}
@ -543,13 +545,43 @@ st_theme_node_get_color (StThemeNode *node,
}
if (inherit && node->parent_node)
return st_theme_node_get_color (node->parent_node, property_name, inherit, color);
return st_theme_node_lookup_color (node->parent_node, property_name, inherit, color);
return FALSE;
}
/**
* st_theme_node_get_double:
* st_theme_node_get_color:
* @node: a #StThemeNode
* @property_name: The name of the color property
* @color: location to store the color that was determined.
*
* Generically looks up a property containing a single color value. When
* specific getters (like st_theme_node_get_background_color()) exist, they
* should be used instead. They are cached, so more efficient, and have
* handling for shortcut properties and other details of CSS.
*
* If @property_name is not found, a warning will be logged and a
* default color returned.
*
* See also st_theme_node_lookup_color(), which provides more options,
* and lets you handle the case where the theme does not specify the
* indicated color.
*/
void
st_theme_node_get_color (StThemeNode *node,
const char *property_name,
ClutterColor *color)
{
if (!st_theme_node_lookup_color (node, property_name, FALSE, color))
{
g_warning ("Did not find color property '%s'", property_name);
memset (color, 0, sizeof (ClutterColor));
}
}
/**
* st_theme_node_lookup_double:
* @node: a #StThemeNode
* @property_name: The name of the numeric property
* @inherit: if %TRUE, if a value is not found for the property on the
@ -564,14 +596,16 @@ st_theme_node_get_color (StThemeNode *node,
* Generically looks up a property containing a single numeric value
* without units.
*
* See also st_theme_node_get_double(), which provides a simpler API.
*
* Return value: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
st_theme_node_get_double (StThemeNode *node,
const char *property_name,
gboolean inherit,
double *value)
st_theme_node_lookup_double (StThemeNode *node,
const char *property_name,
gboolean inherit,
double *value)
{
gboolean result = FALSE;
int i;
@ -596,11 +630,41 @@ st_theme_node_get_double (StThemeNode *node,
}
if (!result && inherit && node->parent_node)
result = st_theme_node_get_double (node->parent_node, property_name, inherit, value);
result = st_theme_node_lookup_double (node->parent_node, property_name, inherit, value);
return result;
}
/**
* st_theme_node_get_double:
* @node: a #StThemeNode
* @property_name: The name of the numeric property
*
* Generically looks up a property containing a single numeric value
* without units.
*
* See also st_theme_node_lookup_double(), which provides more options,
* and lets you handle the case where the theme does not specify the
* indicated value.
*
* Return value: the value found. If @property_name is not
* found, a warning will be logged and 0 will be returned.
*/
gdouble
st_theme_node_get_double (StThemeNode *node,
const char *property_name)
{
gdouble value;
if (st_theme_node_lookup_double (node, property_name, FALSE, &value))
return value;
else
{
g_warning ("Did not find double property '%s'", property_name);
return 0.0;
}
}
static const PangoFontDescription *
get_parent_font (StThemeNode *node)
{
@ -802,7 +866,7 @@ get_length_internal (StThemeNode *node,
}
/**
* st_theme_node_get_length:
* st_theme_node_lookup_length:
* @node: a #StThemeNode
* @property_name: The name of the length property
* @inherit: if %TRUE, if a value is not found for the property on the
@ -820,14 +884,16 @@ get_length_internal (StThemeNode *node,
* should be used instead. They are cached, so more efficient, and have
* handling for shortcut properties and other details of CSS.
*
* See also st_theme_node_get_length(), which provides a simpler API.
*
* Return value: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
st_theme_node_get_length (StThemeNode *node,
const char *property_name,
gboolean inherit,
gdouble *length)
st_theme_node_lookup_length (StThemeNode *node,
const char *property_name,
gboolean inherit,
gdouble *length)
{
GetFromTermResult result = get_length_internal (node, property_name, NULL, length);
if (result == VALUE_FOUND)
@ -836,12 +902,42 @@ st_theme_node_get_length (StThemeNode *node,
inherit = TRUE;
if (inherit && node->parent_node &&
st_theme_node_get_length (node->parent_node, property_name, inherit, length))
st_theme_node_lookup_length (node->parent_node, property_name, inherit, length))
return TRUE;
else
return FALSE;
}
/**
* st_theme_node_get_length:
* @node: a #StThemeNode
* @property_name: The name of the length property
*
* Generically looks up a property containing a single length value. When
* specific getters (like st_theme_node_get_border_width()) exist, they
* should be used instead. They are cached, so more efficient, and have
* handling for shortcut properties and other details of CSS.
*
* Unlike st_theme_node_get_color() and st_theme_node_get_double(),
* this does not print a warning if the property is not found; it just
* returns 0.
*
* See also st_theme_node_lookup_length(), which provides more options.
*
* Return value: the length, in pixels, or 0 if the property was not found.
*/
gdouble
st_theme_node_get_length (StThemeNode *node,
const char *property_name)
{
gdouble length;
if (st_theme_node_lookup_length (node, property_name, FALSE, &length))
return length;
else
return 0.0;
}
static void
do_border_radius_term (StThemeNode *node,
CRTerm *term,
@ -1730,7 +1826,7 @@ st_theme_node_get_transition_duration (StThemeNode *node)
if (node->transition_duration > -1)
return st_slow_down_factor * node->transition_duration;
st_theme_node_get_double (node, "transition-duration", FALSE, &value);
st_theme_node_lookup_double (node, "transition-duration", FALSE, &value);
node->transition_duration = (int)value;

33
src/st/st-theme-node.h
View File

@ -99,20 +99,27 @@ const char *st_theme_node_get_pseudo_class (StThemeNode *node);
* details of the actual CSS rules, which can be complicated, especially
* for fonts
*/
gboolean st_theme_node_get_color (StThemeNode *node,
const char *property_name,
gboolean inherit,
ClutterColor *color);
gboolean st_theme_node_lookup_color (StThemeNode *node,
const char *property_name,
gboolean inherit,
ClutterColor *color);
gboolean st_theme_node_lookup_double (StThemeNode *node,
const char *property_name,
gboolean inherit,
double *value);
gboolean st_theme_node_lookup_length (StThemeNode *node,
const char *property_name,
gboolean inherit,
gdouble *length);
gboolean st_theme_node_get_double (StThemeNode *node,
const char *property_name,
gboolean inherit,
double *value);
gboolean st_theme_node_get_length (StThemeNode *node,
const char *property_name,
gboolean inherit,
gdouble *length);
/* Easier-to-use variants of the above, for application-level use */
void st_theme_node_get_color (StThemeNode *node,
const char *property_name,
ClutterColor *color);
gdouble st_theme_node_get_double (StThemeNode *node,
const char *property_name);
gdouble st_theme_node_get_length (StThemeNode *node,
const char *property_name);
/* Specific getters for particular properties: cached
*/