# GSTheme

fedor@gnu.org
rfm@gnu.org

Useful/configurable drawing functions

2004-2006 Free Software Foundation, Inc.
The theme management system

The theme management system for the GNUstep GUI is based around the GSTheme class, which provides support for loading of theme bundles and methods for drawing common user interface elements.
The theme system works in conjunction with a variety of other GUI classes and is intended to eventually allow for very major changes in GUI appearance and behavior.

Various design imperatives apply to the theme system, but probably the key ones are:

It should allow designers and other non-technical users to easily develop new and interesting GUI styles likely to attract new users to GNUstep.
Using and switching between themes should be an easy and pleasant experience... so that people are not put off when they try using themes.
It should eventually permit a GNUstep application to appear as a native application on ms-windows and other systems.

To attain these aims implies the recognition of some more specific objectives and some possible technical solutions:

We must have as simple as possible an API for the functions handling the way GUI elements work and the way they draw themselves.
The standard OpenStep/MacOS-X API provides mechanisms for controlling the colors used to draw controls (via NSColor and NSColorList ) and controlling the way controls behave (NSInterfaceStyleForKey() and [NSResponder -interfaceStyle]), but we need to extend that with methods to draw controls entirely differently if required.
We must have a GUI application for theme development. It is not sufficient to provide an API if we want good graphic designers and user interface specialists to develop themes for us.
It must be possible for an application to dynamically change the theme in use while it is running and it should be easy for a user to select between available themes.
This implies that themes must be loadable bundles and that it must always be possible to unload a theme as well as loading one.
It suggests that the theme selection mechanism should be in every application, perhaps as an extension to an existing panel such as the info panel.
Types of theming

There are various aspects of theming which can be treated pretty much separately, so there is no reason why a theme might not be created which just employs one of these mechanisms.

System images
Possibly the simples theme change... a theme might supply a new set of system images used for arrows and other icons that the GUI decorates controls with.
System colors
A theme might simply define a new system color list, so that controls are drawn in a new color range, though they would still function the same way. Even specifying new colors can make the GUI look quite different though.
Image tiling
Controls might be given sets of images used as tiling to draw themselves rather than using the standard line drawing and color fill mechanisms.
Interface style
A theme might supply a set of interface style keys for various controls, defining how those controls should behave subject to the limitation of the range of behaviors coded into the GUI library.
Method override
A theme might actually provide code, in the form of a subclass of GSTheme such that drawing methods have completely custom behavior.
Software documentation for the GSTheme class
GNUstepGUI/GSTheme.h

This interface is HIGHLY unstable and incomplete at present.

This is a class used for 'theming', which is mostly a matter of encapsulating common drawing behaviors so that GUI appearance can be easily modified, but also includes mechanisms for altering some GUI behavior (such as orientation and position of menus).

Methods in this class standardize drawing of buttons, borders and other common GUI elements, so that all other classes within the GUI will provide a consistent appearance by using these methods.

The default implementation uses the standard configurable colors defined in NSColor, such as `controlLightHighlightColor`, `controlShadowColor` and `controlDarkShadowColor`.
Themes are expected to override the default system color list with their own versions, and this class cooperates with NSColor and NSColorList to establish the correct system color list when a theme is activated.

The class provides a mechanism for automatic loading of theme bundles consisting of resources used to define how drawing is done, plus an optional binary subclass of this class (to replace/extend the drawing methods this class provides).

In future this class should provide mechanisms to draw controls by tiling of images, and provide control over GUI behavior by controlling the values returned by NSInterfaceStyleForKey() so that controls use the appropriate behavior.

orderFrontSharedThemePanel:
sender
Creates and displays a panel allowing selection of different themes and display of the current theme inspector.
setTheme:
theme
Set the currently active theme to be the instance specified.
You do not normally need to call this method as it is called automatically when the user default which specifies the current theme (GSTheme) is updated.
theme
Returns the currently active theme instance. This is the value most recently set using +setTheme: or (if none has been set) is a default instance of the base class.
activate

This method is called automatically when the receiver is made into the currently active theme by the +setTheme: method. Subclasses may override it to perform startup operations, but should call the super class implementation after doing their own thing.

The base implementation handles setup and caching of the system color list, standard image information, tiling information, and user defaults.
It then sends a GSThemeWillActivateNotification and a GSThemeDidActivateNotification to allow other parts of the GUI library to update themselves from the new theme.

Finally, this method marks all windows in the application as needing update... so they will draw themselves with the new theme information.

authors
Returns the names of the theme's authors.
bundle
Return the bundle containing the resources used by the current theme.
colorNamed:
aName
state:
elementState
cache:
useCache
This returns the color for drawing the item whose name is aName in the specified state. If aName is `nil` or if there is no color defined for the particular combination of item name and state, the method returns `nil`.
The useCache argument controls whether the information is retrieved from cache or regenerated from information in the theme bundle.
colors
Returns the system color list defined by the receiver.
The default implementation returns the color list provided in the theme bundle (if any) or the default system color list.
deactivate

This method is called automatically when the receiver is stopped from being the currently active theme by the use of the +setTheme: method to make another theme active. Subclasses may override it to perform shutdown operations, but should call the super class implementation after their own.

The base implementation handles some cleanup and then sends a GSThemeDidDeactivateNotification to allow other parts of the GUI library to update themselves.

icon
Returns the theme's icon.
infoDictionary

Returns the info dictionary for this theme. In the base class implementation this is simply the info dictionary of the theme bundle, but subclasses may override this method to return extra or different information.

Keys found in this dictionary include:

GSThemeDomain
A dictionary whose key/value pairs are used to set up new values in the GSThemeDomain domain of the user defaults system, and hence define values for these unless overridden by values set explicitly by the user.
GSThemeTiles
A dictionary keyed on tile names and containing the following:
FileName
Name of the file (within the GSThemeTiles directory in the bundle) in which the image for this tile is tored.
HorizontalDivision
The offet along the X-axis used to divide the image into columns of tiles.
VerticalDivision
The offet along the Y-axis used to divide the image into rows of tiles.
initWithBundle:
bundle
Initialise an instance of a theme with the specified resource bundle.
You don't need to call this method directly, but if you are subclassing you may need to override this to provide additional initialisation.
name
Return the theme's name.
nameForElement:
anObject
Returns the name used to locate theming resources for a particular gui element. If no name has been set for the particular object this method returns `nil`.
setName:
aString
Set the name of this theme... used for testing by Thematic.app
setName:
aString
forElement:
anObject
temporary:
takeOwnership
Set the name that is used to identify theming resources for a particular control or other gui element. This is used so that where an element is part of a control it can be displayed differently from the same class of element used outside that control.
Supplying a `nil` value for aString simply removes any name setting for anObject.
Supplying `nil` for anObject is illegal (raises an exception) unless the value of aString is also `nil` (and the method does nothing).
Any control which uses this method to set names for subsidiary elements must also make sure to remove the name mapping before that element is deallocated, unless the takeOwnership option is `YES`, in which case anObject is retained, the name mapping lasts only until the receiver is deactivated, and at that point anObject is released.
themeInspector

Provides a standard inspector window used to display information about the receiver. The default implementation displays the icon, the name, and the authors of the theme.

The code managing this object (if any) must be prepared to have the content view of the window reparented into another window for display on screen.

tilesNamed:
aName
state:
elementState
cache:
useCache
Returns the tile image information for a particular image name, or `nil` if there is no such information or the name is `nil`.
The GUI library uses this internally to handling tiling of image information to draw user interface elements. The tile information returned by this method can be passed to the -fillRect:withTiles:background:fillStyle: method.
The elementState argument specifies the state for which tiles are requested.
The useCache argument controls whether the information is retrieved from cache or regenerated from information in the theme bundle.
Software documentation for the GSTheme(Drawing) category
GNUstepGUI/GSTheme.h
Theme drawing methods
buttonBorderForCell:
cell
style:
style
state:
state
Amount by which the button is inset by the border.
cellForScrollerArrow:
part
horizontal:
horizontal
Methods for scroller theming.
cellForScrollerKnob:
horizontal
Description forthcoming.
cellForScrollerKnobSlot:
horizontal
Description forthcoming.
defaultScrollerWidth
Description forthcoming.
drawBorderForImageFrameStyle:
frameStyle
frame:
frame
view:
view
Draw a border of the specified frame style.
drawBorderType:
aType
frame:
frame
view:
view
Draw a border of the specified border type.
drawButton:
frame
in:
cell
view:
view
style:
style
state:
state
Draws a button frame and background (not its content) for the specified cell and view.
drawFocusFrame:
frame
view:
view
Draws the indicator (normally a dotted rectangle) to show that the view currently has keyboard focus.
drawToobarRect:
aRect
frame:
viewFrame
borderMask:
borderMask
Method for toolbar theming.
drawWindowBackground:
frame
view:
view
Draws the background of a window... normally a simple fill with the the window's background color.
sizeForBorderType:
aType
Determine the size for the specified border type.
sizeForImageFrameStyle:
frameStyle
Determine the size for the specified frame style.
Software documentation for the GSTheme(LowLevelDrawing) category
GNUstepGUI/GSTheme.h
Low level drawiong methods... themes may use these for drawing, but should not normally override them.
fillHorizontalRect:
rect
withImage:
image
fromRect:
source
flipped:
flipped
Method to tile the supplied image to fill the horizontal rectangle.
The rect argument is the rectangle to be filled.
The image argument is the data to fill with.
The source argument is the rectangle within the image which is used.
The flipped argument specifies what sort of coordinate system is in use in the view where we are drawing.
fillRect:
rect
withRepeatedImage:
image
fromRect:
source
center:
center
Tile rect with image. The tiling starts with the origin of the first copy of the image at the bottom left corner of the rect unless center is `YES`, in which case the image is centered in rect and tiled outwards from that.
fillRect:
rect
withTiles:
tiles
background:
color
fillStyle:
style
Method to tile a rectangle given a group of up to nine tile images.
The GSDrawTiles object encapsulates the tile images and information about what parts of each image are used for tiling.
This draws the left, right, top and bottom borders by tiling the images at left, right, top and bottom. It then draws the four corner images and finally deals with the remaining space in the middle according to the specified style.
The background color specified is used to fill the center where style is FillStyleNone.
The return value is the central rectangle (inside the border images).
fillVerticalRect:
rect
withImage:
image
fromRect:
source
flipped:
flipped
Method to tile the supplied image to fill the vertical rectangle.
The rect argument is the rectangle to be filled.
The image argument is the data to fill with.
The source argument is the rectangle within the image which is used.
The flipped argument specifies what sort of coordinate system is in use in the view where we are drawing.
Software documentation for the GSTheme(MidLevelDrawing) category
GNUstepGUI/GSTheme.h
Helper functions for drawing standard items.
drawButton:
border
withClip:
clip
Draw a standard button
drawDarkBezel:
border
withClip:
clip
Draw a dark bezel border
drawDarkButton:
border
withClip:
clip
Draw a "dark" button border (used in tableviews)
drawFramePhoto:
border
withClip:
clip
Draw a frame photo border. Used in NSImageView.
drawGradientBorder:
gradientType
inRect:
border
withClip:
clip
Draw a gradient border.
drawGrayBezel:
border
withClip:
clip
Draw a grey bezel border
drawGroove:
border
withClip:
clip
Draw a groove border
drawLightBezel:
border
withClip:
clip
Draw a light bezel border
drawWhiteBezel:
border
withClip:
clip
Draw a white bezel border