Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
- Exported types
- Methods
- Overloaded methods
- addClass
- addProvider
- addProviderForDisplay
- getBorder
- getColor
- getDisplay
- getMargin
- getPadding
- getParent
- getPath
- getProperty
- getScale
- getState
- hasClass
- listClasses
- lookupColor
- new
- removeClass
- removeProvider
- removeProviderForDisplay
- resetWidgets
- restore
- save
- setDisplay
- setParent
- setPath
- setScale
- setState
- toString
- Properties
- Signals
StyleContext
is an object that stores styling information affecting
a widget defined by WidgetPath
.
In order to construct the final style information, StyleContext
queries information from all attached GtkStyleProviders
. Style providers
can be either attached explicitly to the context through
styleContextAddProvider
, or to the display through
styleContextAddProviderForDisplay
. The resulting style is a
combination of all providers’ information in priority order.
For GTK+ widgets, any StyleContext
returned by
widgetGetStyleContext
will already have a WidgetPath
, a
Display
and RTL/LTR information set. The style context will also be
updated automatically if any of these settings change on the widget.
If you are using the theming layer standalone, you will need to set a
widget path and a display yourself to the created style context through
styleContextSetPath
and possibly styleContextSetDisplay
.
See the “Foreign drawing“ example in gtk4-demo.
Widgets can add style classes to their context, which can be used to associate different styles by class. The documentation for individual widgets lists which style classes it uses itself, and which style classes may be added by applications to affect their appearance.
GTK+ defines macros for a number of style classes.
Custom styling in UI libraries and applications
If you are developing a library with custom GtkWidgets
that
render differently than standard components, you may need to add a
StyleProvider
yourself with the STYLE_PROVIDER_PRIORITY_FALLBACK
priority, either a CssProvider
or a custom object implementing the
StyleProvider
interface. This way themes may still attempt
to style your UI elements in a different way if needed so.
If you are using custom styling on an applications, you probably want then
to make your style information prevail to the theme’s, so you must use
a StyleProvider
with the STYLE_PROVIDER_PRIORITY_APPLICATION
priority, keep in mind that the user settings in
XDG_CONFIG_HOME/gtk-4.0/gtk.css
will
still take precedence over your changes, as it uses the
STYLE_PROVIDER_PRIORITY_USER
priority.
Synopsis
- newtype StyleContext = StyleContext (ManagedPtr StyleContext)
- class (GObject o, IsDescendantOf StyleContext o) => IsStyleContext o
- toStyleContext :: (MonadIO m, IsStyleContext o) => o -> m StyleContext
- noStyleContext :: Maybe StyleContext
- styleContextAddClass :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> Text -> m ()
- styleContextAddProvider :: (HasCallStack, MonadIO m, IsStyleContext a, IsStyleProvider b) => a -> b -> Word32 -> m ()
- styleContextAddProviderForDisplay :: (HasCallStack, MonadIO m, IsDisplay a, IsStyleProvider b) => a -> b -> Word32 -> m ()
- styleContextGetBorder :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m Border
- styleContextGetColor :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m RGBA
- styleContextGetDisplay :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m Display
- styleContextGetMargin :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m Border
- styleContextGetPadding :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m Border
- styleContextGetParent :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m (Maybe StyleContext)
- styleContextGetPath :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m WidgetPath
- styleContextGetProperty :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> Text -> m GValue
- styleContextGetScale :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m Int32
- styleContextGetState :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m [StateFlags]
- styleContextHasClass :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> Text -> m Bool
- styleContextListClasses :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m [Text]
- styleContextLookupColor :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> Text -> m (Bool, RGBA)
- styleContextNew :: (HasCallStack, MonadIO m) => m StyleContext
- styleContextRemoveClass :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> Text -> m ()
- styleContextRemoveProvider :: (HasCallStack, MonadIO m, IsStyleContext a, IsStyleProvider b) => a -> b -> m ()
- styleContextRemoveProviderForDisplay :: (HasCallStack, MonadIO m, IsDisplay a, IsStyleProvider b) => a -> b -> m ()
- styleContextResetWidgets :: (HasCallStack, MonadIO m, IsDisplay a) => a -> m ()
- styleContextRestore :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m ()
- styleContextSave :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> m ()
- styleContextSetDisplay :: (HasCallStack, MonadIO m, IsStyleContext a, IsDisplay b) => a -> b -> m ()
- styleContextSetParent :: (HasCallStack, MonadIO m, IsStyleContext a, IsStyleContext b) => a -> Maybe b -> m ()
- styleContextSetPath :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> WidgetPath -> m ()
- styleContextSetScale :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> Int32 -> m ()
- styleContextSetState :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> [StateFlags] -> m ()
- styleContextToString :: (HasCallStack, MonadIO m, IsStyleContext a) => a -> [StyleContextPrintFlags] -> m Text
- constructStyleContextDisplay :: (IsStyleContext o, IsDisplay a) => a -> IO (GValueConstruct o)
- getStyleContextDisplay :: (MonadIO m, IsStyleContext o) => o -> m Display
- setStyleContextDisplay :: (MonadIO m, IsStyleContext o, IsDisplay a) => o -> a -> m ()
- clearStyleContextParent :: (MonadIO m, IsStyleContext o) => o -> m ()
- constructStyleContextParent :: (IsStyleContext o, IsStyleContext a) => a -> IO (GValueConstruct o)
- getStyleContextParent :: (MonadIO m, IsStyleContext o) => o -> m (Maybe StyleContext)
- setStyleContextParent :: (MonadIO m, IsStyleContext o, IsStyleContext a) => o -> a -> m ()
- type C_StyleContextChangedCallback = Ptr () -> Ptr () -> IO ()
- type StyleContextChangedCallback = IO ()
- afterStyleContextChanged :: (IsStyleContext a, MonadIO m) => a -> StyleContextChangedCallback -> m SignalHandlerId
- genClosure_StyleContextChanged :: MonadIO m => StyleContextChangedCallback -> m (GClosure C_StyleContextChangedCallback)
- mk_StyleContextChangedCallback :: C_StyleContextChangedCallback -> IO (FunPtr C_StyleContextChangedCallback)
- noStyleContextChangedCallback :: Maybe StyleContextChangedCallback
- onStyleContextChanged :: (IsStyleContext a, MonadIO m) => a -> StyleContextChangedCallback -> m SignalHandlerId
- wrap_StyleContextChangedCallback :: StyleContextChangedCallback -> C_StyleContextChangedCallback
Exported types
newtype StyleContext Source #
Memory-managed wrapper type.
Instances
Eq StyleContext Source # | |
Defined in GI.Gtk.Objects.StyleContext (==) :: StyleContext -> StyleContext -> Bool # (/=) :: StyleContext -> StyleContext -> Bool # | |
IsGValue StyleContext Source # | Convert |
Defined in GI.Gtk.Objects.StyleContext toGValue :: StyleContext -> IO GValue # fromGValue :: GValue -> IO StyleContext # | |
GObject StyleContext Source # | |
Defined in GI.Gtk.Objects.StyleContext gobjectType :: IO GType # | |
HasParentTypes StyleContext Source # | |
Defined in GI.Gtk.Objects.StyleContext | |
type ParentTypes StyleContext Source # | |
Defined in GI.Gtk.Objects.StyleContext |
class (GObject o, IsDescendantOf StyleContext o) => IsStyleContext o Source #
Type class for types which can be safely cast to StyleContext
, for instance with toStyleContext
.
Instances
(GObject o, IsDescendantOf StyleContext o) => IsStyleContext o Source # | |
Defined in GI.Gtk.Objects.StyleContext |
toStyleContext :: (MonadIO m, IsStyleContext o) => o -> m StyleContext Source #
Cast to StyleContext
, for types for which this is known to be safe. For general casts, use castTo
.
noStyleContext :: Maybe StyleContext Source #
A convenience alias for Nothing
:: Maybe
StyleContext
.
Methods
Overloaded methods
addClass
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> Text |
|
-> m () |
Adds a style class to context
, so posterior calls to
gtk_style_context_get()
or any of the gtk_render_*()
functions will make use of this new class for styling.
In the CSS file format, a Entry
defining a “search”
class, would be matched by:
<!-- language="CSS" --> entry.search { ... }
While any widget defining a “search” class would be matched by: > language="CSS" -- >.search { ... }
addProvider
styleContextAddProvider Source #
:: (HasCallStack, MonadIO m, IsStyleContext a, IsStyleProvider b) | |
=> a |
|
-> b |
|
-> Word32 |
|
-> m () |
Adds a style provider to context
, to be used in style construction.
Note that a style provider added by this function only affects
the style of the widget to which context
belongs. If you want
to affect the style of all widgets, use
styleContextAddProviderForDisplay
.
Note: If both priorities are the same, a StyleProvider
added through this function takes precedence over another added
through styleContextAddProviderForDisplay
.
addProviderForDisplay
styleContextAddProviderForDisplay Source #
:: (HasCallStack, MonadIO m, IsDisplay a, IsStyleProvider b) | |
=> a |
|
-> b |
|
-> Word32 |
|
-> m () |
Adds a global style provider to display
, which will be used
in style construction for all GtkStyleContexts
under display
.
GTK+ uses this to make styling information from Settings
available.
Note: If both priorities are the same, A StyleProvider
added through styleContextAddProvider
takes precedence
over another added through this function.
getBorder
styleContextGetBorder Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m Border |
Gets the border for a given state as a Border
.
See styleContextGetProperty
and
STYLE_PROPERTY_BORDER_WIDTH
for details.
getColor
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m RGBA |
Gets the foreground color for a given state.
See styleContextGetProperty
and
STYLE_PROPERTY_COLOR
for details.
getDisplay
styleContextGetDisplay Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m Display | Returns: a |
Returns the Display
to which context
is attached.
getMargin
styleContextGetMargin Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m Border |
Gets the margin for a given state as a Border
.
See gtk_style_property_get()
and STYLE_PROPERTY_MARGIN
for details.
getPadding
styleContextGetPadding Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m Border |
Gets the padding for a given state as a Border
.
See gtk_style_context_get()
and STYLE_PROPERTY_PADDING
for details.
getParent
styleContextGetParent Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m (Maybe StyleContext) | Returns: the parent context or |
Gets the parent context set via styleContextSetParent
.
See that function for details.
getPath
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m WidgetPath | Returns: A |
Returns the widget path used for style matching.
getProperty
styleContextGetProperty Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> Text |
|
-> m GValue |
Gets a style property from context
for the current state.
Note that not all CSS properties that are supported by GTK+ can be
retrieved in this way, since they may not be representable as Value
.
GTK+ defines macros for a number of properties that can be used
with this function.
When value
is no longer needed, valueUnset
must be called
to free any allocated memory.
getScale
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m Int32 | Returns: the scale |
Returns the scale used for assets.
getState
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m [StateFlags] | Returns: the state flags |
Returns the state used for style matching.
This method should only be used to retrieve the StateFlags
to pass to StyleContext
methods, like styleContextGetPadding
.
If you need to retrieve the current state of a Widget
, use
widgetGetStateFlags
.
hasClass
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> Text |
|
-> m Bool | Returns: |
Returns True
if context
currently has defined the
given class name.
listClasses
styleContextListClasses Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m [Text] | Returns: a |
Returns the list of classes currently defined in context
.
lookupColor
styleContextLookupColor Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> Text |
|
-> m (Bool, RGBA) | Returns: |
Looks up and resolves a color name in the context
color map.
new
:: (HasCallStack, MonadIO m) | |
=> m StyleContext | Returns: A newly created |
Creates a standalone StyleContext
, this style context
won’t be attached to any widget, so you may want
to call styleContextSetPath
yourself.
This function is only useful when using the theming layer
separated from GTK+, if you are using StyleContext
to
theme GtkWidgets
, use widgetGetStyleContext
in order to get a style context ready to theme the widget.
removeClass
styleContextRemoveClass Source #
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> Text |
|
-> m () |
Removes className
from context
.
removeProvider
styleContextRemoveProvider Source #
:: (HasCallStack, MonadIO m, IsStyleContext a, IsStyleProvider b) | |
=> a |
|
-> b |
|
-> m () |
Removes provider
from the style providers list in context
.
removeProviderForDisplay
styleContextRemoveProviderForDisplay Source #
:: (HasCallStack, MonadIO m, IsDisplay a, IsStyleProvider b) | |
=> a |
|
-> b |
|
-> m () |
Removes provider
from the global style providers list in display
.
resetWidgets
styleContextResetWidgets Source #
:: (HasCallStack, MonadIO m, IsDisplay a) | |
=> a |
|
-> m () |
This function recomputes the styles for all widgets under a particular
Display
. This is useful when some global parameter has changed that
affects the appearance of all widgets, because when a widget gets a new
style, it will both redraw and recompute any cached information about
its appearance. As an example, it is used when the color scheme changes
in the related Settings
object.
restore
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m () |
Restores context
state to a previous stage.
See styleContextSave
.
save
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> m () |
Saves the context
state, so temporary modifications done through
styleContextAddClass
, styleContextRemoveClass
,
styleContextSetState
, etc. can quickly be reverted
in one go through styleContextRestore
.
The matching call to styleContextRestore
must be done
before GTK returns to the main loop.
setDisplay
styleContextSetDisplay Source #
:: (HasCallStack, MonadIO m, IsStyleContext a, IsDisplay b) | |
=> a |
|
-> b |
|
-> m () |
Attaches context
to the given display.
The display is used to add style information from “global” style
providers, such as the display's Settings
instance.
If you are using a StyleContext
returned from
widgetGetStyleContext
, you do not need to
call this yourself.
setParent
styleContextSetParent Source #
:: (HasCallStack, MonadIO m, IsStyleContext a, IsStyleContext b) | |
=> a |
|
-> Maybe b |
|
-> m () |
Sets the parent style context for context
. The parent style
context is used to implement
inheritance
of properties.
If you are using a StyleContext
returned from
widgetGetStyleContext
, the parent will be set for you.
setPath
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> WidgetPath |
|
-> m () |
Sets the WidgetPath
used for style matching. As a
consequence, the style will be regenerated to match
the new given path.
If you are using a StyleContext
returned from
widgetGetStyleContext
, you do not need to call
this yourself.
setScale
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> Int32 |
|
-> m () |
Sets the scale to use when getting image assets for the style.
setState
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> [StateFlags] |
|
-> m () |
Sets the state to be used for style matching.
toString
:: (HasCallStack, MonadIO m, IsStyleContext a) | |
=> a |
|
-> [StyleContextPrintFlags] |
|
-> m Text | Returns: a newly allocated string representing |
Converts the style context into a string representation.
The string representation always includes information about
the name, state, id, visibility and style classes of the CSS
node that is backing context
. Depending on the flags, more
information may be included.
This function is intended for testing and debugging of the CSS implementation in GTK+. There are no guarantees about the format of the returned string, it may change.
Properties
display
No description available in the introspection data.
constructStyleContextDisplay :: (IsStyleContext o, IsDisplay a) => a -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “display
” property. This is rarely needed directly, but it is used by new
.
getStyleContextDisplay :: (MonadIO m, IsStyleContext o) => o -> m Display Source #
Get the value of the “display
” property.
When overloading is enabled, this is equivalent to
get
styleContext #display
setStyleContextDisplay :: (MonadIO m, IsStyleContext o, IsDisplay a) => o -> a -> m () Source #
Set the value of the “display
” property.
When overloading is enabled, this is equivalent to
set
styleContext [ #display:=
value ]
parent
Sets or gets the style context’s parent. See styleContextSetParent
for details.
clearStyleContextParent :: (MonadIO m, IsStyleContext o) => o -> m () Source #
Set the value of the “parent
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#parent
constructStyleContextParent :: (IsStyleContext o, IsStyleContext a) => a -> IO (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “parent
” property. This is rarely needed directly, but it is used by new
.
getStyleContextParent :: (MonadIO m, IsStyleContext o) => o -> m (Maybe StyleContext) Source #
Get the value of the “parent
” property.
When overloading is enabled, this is equivalent to
get
styleContext #parent
setStyleContextParent :: (MonadIO m, IsStyleContext o, IsStyleContext a) => o -> a -> m () Source #
Set the value of the “parent
” property.
When overloading is enabled, this is equivalent to
set
styleContext [ #parent:=
value ]
Signals
changed
type C_StyleContextChangedCallback = Ptr () -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type StyleContextChangedCallback = IO () Source #
The changed signal is emitted when there is a change in the
StyleContext
.
For a StyleContext
returned by widgetGetStyleContext
, the
styleUpdated signal/vfunc might be more convenient to use.
This signal is useful when using the theming layer standalone.
afterStyleContextChanged :: (IsStyleContext a, MonadIO m) => a -> StyleContextChangedCallback -> m SignalHandlerId Source #
Connect a signal handler for the changed signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
styleContext #changed callback
genClosure_StyleContextChanged :: MonadIO m => StyleContextChangedCallback -> m (GClosure C_StyleContextChangedCallback) Source #
Wrap the callback into a GClosure
.
mk_StyleContextChangedCallback :: C_StyleContextChangedCallback -> IO (FunPtr C_StyleContextChangedCallback) Source #
Generate a function pointer callable from C code, from a C_StyleContextChangedCallback
.
noStyleContextChangedCallback :: Maybe StyleContextChangedCallback Source #
A convenience synonym for
.Nothing
:: Maybe
StyleContextChangedCallback
onStyleContextChanged :: (IsStyleContext a, MonadIO m) => a -> StyleContextChangedCallback -> m SignalHandlerId Source #
Connect a signal handler for the changed signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
styleContext #changed callback