Up

# GSTheme

### Authors

Adam Fedor (`fedor@gnu.org`)
Richard Frith-Macdonald (`rfm@gnu.org`)

> Useful/configurable drawing functions

Copyright: (C) 2004-2006 Free Software Foundation, Inc.

### Contents -

1. The theme management system
2. Types of theming
3. Software documentation for the GSTheme class
4. Software documentation for the GSTheme(Drawing) category
5. Software documentation for the GSTheme(LowLevelDrawing) category
6. Software documentation for the GSTheme(MidLevelDrawing) category

# 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

## GSTheme : NSObject

> Declared in:
>   GNUstepGUI/GSTheme.h

Availability: Not in OpenStep/MacOS-X

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.

Method summary

- -buttonBorderForCell:style:state:
- -cellForScrollerArrow:horizontal:
- -cellForScrollerKnob:
- -cellForScrollerKnobSlot:
- -defaultScrollerWidth
- -drawBorderForImageFrameStyle:frame:view:
- -drawBorderType:frame:view:
- -drawButton:in:view:style:state:
- -drawFocusFrame:view:
- -drawToobarRect:frame:borderMask:
- -drawWindowBackground:view:
- -sizeForBorderType:
- -sizeForImageFrameStyle:
- -fillHorizontalRect:withImage:fromRect:flipped:
- -fillRect:withRepeatedImage:fromRect:center:
- -fillRect:withTiles:background:fillStyle:
- -fillVerticalRect:withImage:fromRect:flipped:
- -drawButton:withClip:
- -drawDarkBezel:withClip:
- -drawDarkButton:withClip:
- -drawFramePhoto:withClip:
- -drawGradientBorder:inRect:withClip:
- -drawGrayBezel:withClip:
- -drawGroove:withClip:
- -drawLightBezel:withClip:
- -drawWhiteBezel:withClip:
- +orderFrontSharedThemePanel:
- +setTheme:
- +theme
- -activate
- -authors
- -bundle
- -colorNamed:state:cache:
- -colors
- -deactivate
- -icon
- -infoDictionary
- -initWithBundle:
- -name
- -nameForElement:
- -setName:
- -setName:forElement:temporary:
- -themeInspector
- -tilesNamed:state:cache:

### orderFrontSharedThemePanel:

+ (void) orderFrontSharedThemePanel: (id)sender;
Availability: Not in OpenStep/MacOS-X
Creates and displays a panel allowing selection of different themes and display of the current theme inspector.

### setTheme:

+ (void) setTheme: (GSTheme*)theme;
Availability: Not in OpenStep/MacOS-X
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

+ (GSTheme*) theme;
Availability: Not in OpenStep/MacOS-X
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

- (void) activate;
Availability: Not in OpenStep/MacOS-X

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

- (NSArray*) authors;
Availability: Not in OpenStep/MacOS-X
Returns the names of the theme's authors.

### bundle

- (NSBundle*) bundle;
Availability: Not in OpenStep/MacOS-X
Return the bundle containing the resources used by the current theme.

### colorNamed: state: cache:

- (NSColor*) colorNamed: (NSString*)aName state: (GSThemeControlState)elementState cache: (BOOL)useCache;
Availability: Not in OpenStep/MacOS-X
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

- (NSColorList*) colors;
Availability: Not in OpenStep/MacOS-X
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

- (void) deactivate;
Availability: Not in OpenStep/MacOS-X

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

- (NSImage*) icon;
Availability: Not in OpenStep/MacOS-X
Returns the theme's icon.

### infoDictionary

- (NSDictionary*) infoDictionary;
Availability: Not in OpenStep/MacOS-X

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:

- (id) initWithBundle: (NSBundle*)bundle;
Availability: Not in OpenStep/MacOS-X
This is a designated initialiser for the class.
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

- (NSString*) name;
Availability: Not in OpenStep/MacOS-X
Return the theme's name.

### nameForElement:

- (NSString*) nameForElement: (id)anObject;
Availability: Not in OpenStep/MacOS-X
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:

- (void) setName: (NSString*)aString;
Availability: Not in OpenStep/MacOS-X
Set the name of this theme... used for testing by Thematic.app

### setName: forElement: temporary:

- (void) setName: (NSString*)aString forElement: (id)anObject temporary: (BOOL)takeOwnership;
Availability: Not in OpenStep/MacOS-X
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

- (NSWindow*) themeInspector;
Availability: Not in OpenStep/MacOS-X

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: state: cache:

- (GSDrawTiles*) tilesNamed: (NSString*)aName state: (GSThemeControlState)elementState cache: (BOOL)useCache;
Availability: Not in OpenStep/MacOS-X
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

## GSTheme(Drawing)

> Declared in:
>   GNUstepGUI/GSTheme.h

Availability: Not in OpenStep/MacOS-X
Theme drawing methods
Method summary

- -buttonBorderForCell:style:state:
- -cellForScrollerArrow:horizontal:
- -cellForScrollerKnob:
- -cellForScrollerKnobSlot:
- -defaultScrollerWidth
- -drawBorderForImageFrameStyle:frame:view:
- -drawBorderType:frame:view:
- -drawButton:in:view:style:state:
- -drawFocusFrame:view:
- -drawToobarRect:frame:borderMask:
- -drawWindowBackground:view:
- -sizeForBorderType:
- -sizeForImageFrameStyle:

### buttonBorderForCell: style: state:

- (NSSize) buttonBorderForCell: (NSCell*)cell style: (int)style state: (GSThemeControlState)state;
Availability: Not in OpenStep/MacOS-X
Amount by which the button is inset by the border.

### cellForScrollerArrow: horizontal:

- (NSButtonCell*) cellForScrollerArrow: (NSScrollerArrow)part horizontal: (BOOL)horizontal;
Availability: Not in OpenStep/MacOS-X
Methods for scroller theming.

### cellForScrollerKnob:

- (NSCell*) cellForScrollerKnob: (BOOL)horizontal;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### cellForScrollerKnobSlot:

- (NSCell*) cellForScrollerKnobSlot: (BOOL)horizontal;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### defaultScrollerWidth

- (float) defaultScrollerWidth;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### drawBorderForImageFrameStyle: frame: view:

- (void) drawBorderForImageFrameStyle: (NSImageFrameStyle)frameStyle frame: (NSRect)frame view: (NSView*)view;
Availability: Not in OpenStep/MacOS-X
Draw a border of the specified frame style.

### drawBorderType: frame: view:

- (void) drawBorderType: (NSBorderType)aType frame: (NSRect)frame view: (NSView*)view;
Availability: Not in OpenStep/MacOS-X
Draw a border of the specified border type.

### drawButton: in: view: style: state:

- (void) drawButton: (NSRect)frame in: (NSCell*)cell view: (NSView*)view style: (int)style state: (GSThemeControlState)state;
Availability: Not in OpenStep/MacOS-X
Draws a button frame and background (not its content) for the specified cell and view.

### drawFocusFrame: view:

- (void) drawFocusFrame: (NSRect)frame view: (NSView*)view;
Availability: Not in OpenStep/MacOS-X
Draws the indicator (normally a dotted rectangle) to show that the view currently has keyboard focus.

### drawToobarRect: frame: borderMask:

- (void) drawToobarRect: (NSRect)aRect frame: (NSRect)viewFrame borderMask: (unsigned int)borderMask;
Availability: Not in OpenStep/MacOS-X
Method for toolbar theming.

### drawWindowBackground: view:

- (void) drawWindowBackground: (NSRect)frame view: (NSView*)view;
Availability: Not in OpenStep/MacOS-X
Draws the background of a window... normally a simple fill with the the window's background color.

### sizeForBorderType:

- (NSSize) sizeForBorderType: (NSBorderType)aType;
Availability: Not in OpenStep/MacOS-X
Determine the size for the specified border type.

### sizeForImageFrameStyle:

- (NSSize) sizeForImageFrameStyle: (NSImageFrameStyle)frameStyle;
Availability: Not in OpenStep/MacOS-X
Determine the size for the specified frame style.

# Software documentation for the GSTheme(LowLevelDrawing) category

## GSTheme(LowLevelDrawing)

> Declared in:
>   GNUstepGUI/GSTheme.h

Availability: Not in OpenStep/MacOS-X
Low level drawiong methods... themes may use these for drawing, but should not normally override them.
Method summary

- -fillHorizontalRect:withImage:fromRect:flipped:
- -fillRect:withRepeatedImage:fromRect:center:
- -fillRect:withTiles:background:fillStyle:
- -fillVerticalRect:withImage:fromRect:flipped:

### fillHorizontalRect: withImage: fromRect: flipped:

- (void) fillHorizontalRect: (NSRect)rect withImage: (NSImage*)image fromRect: (NSRect)source flipped: (BOOL)flipped;
Availability: Not in OpenStep/MacOS-X
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: withRepeatedImage: fromRect: center:

- (void) fillRect: (NSRect)rect withRepeatedImage: (NSImage*)image fromRect: (NSRect)source center: (BOOL)center;
Availability: Not in OpenStep/MacOS-X
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: withTiles: background: fillStyle:

- (NSRect) fillRect: (NSRect)rect withTiles: (GSDrawTiles*)tiles background: (NSColor*)color fillStyle: (GSThemeFillStyle)style;
Availability: Not in OpenStep/MacOS-X
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: withImage: fromRect: flipped:

- (void) fillVerticalRect: (NSRect)rect withImage: (NSImage*)image fromRect: (NSRect)source flipped: (BOOL)flipped;
Availability: Not in OpenStep/MacOS-X
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

## GSTheme(MidLevelDrawing)

> Declared in:
>   GNUstepGUI/GSTheme.h

Availability: Not in OpenStep/MacOS-X
Helper functions for drawing standard items.
Method summary

- -drawButton:withClip:
- -drawDarkBezel:withClip:
- -drawDarkButton:withClip:
- -drawFramePhoto:withClip:
- -drawGradientBorder:inRect:withClip:
- -drawGrayBezel:withClip:
- -drawGroove:withClip:
- -drawLightBezel:withClip:
- -drawWhiteBezel:withClip:

### drawButton: withClip:

- (NSRect) drawButton: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a standard button

### drawDarkBezel: withClip:

- (NSRect) drawDarkBezel: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a dark bezel border

### drawDarkButton: withClip:

- (NSRect) drawDarkButton: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a "dark" button border (used in tableviews)

### drawFramePhoto: withClip:

- (NSRect) drawFramePhoto: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a frame photo border. Used in NSImageView.

### drawGradientBorder: inRect: withClip:

- (NSRect) drawGradientBorder: (NSGradientType)gradientType inRect: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a gradient border.

### drawGrayBezel: withClip:

- (NSRect) drawGrayBezel: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a grey bezel border

### drawGroove: withClip:

- (NSRect) drawGroove: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a groove border

### drawLightBezel: withClip:

- (NSRect) drawLightBezel: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a light bezel border

### drawWhiteBezel: withClip:

- (NSRect) drawWhiteBezel: (NSRect)border withClip: (NSRect)clip;
Availability: Not in OpenStep/MacOS-X
Draw a white bezel border

Up