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:

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

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 mas 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

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 GSThemeDidActivateNotification to allow other parts of the GUI library to update themselves from the new theme.
If the theme sets an alternative system color list, the notification userInfo dictionary will contain that list keyed on Colors.

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.

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.

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

- (GSDrawTiles*) tilesNamed: (NSString*)aName 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.
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 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

buttonBorderForStyle: state: 

- (NSSize) buttonBorderForStyle: (int)style state: (GSThemeControlState)state;
Availability: Not in OpenStep/MacOS-X

Amount by which the button is inset by the border.

drawButton: in: view: style: state: 

- (void) drawButton: (NSRect)frame in: (NSButtonCell*)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.

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.

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: 

- (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: 

- (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