/** GSTheme Useful/configurable drawing functions Copyright (C) 2004-2006 Free Software Foundation, Inc. Author: Adam Fedor Author: Richard Frith-Macdonald Date: Jan 2004 This file is part of the GNU Objective C User interface library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; see the file COPYING.LIB. If not, see or write to the Free Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 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.
*/ #ifndef _GNUstep_H_GSTheme #define _GNUstep_H_GSTheme #include #include #include // For gradient types #include // For image frame style #include // For scroller constants #include #if OS_API_VERSION(GS_API_NONE,GS_API_NONE) @class NSArray; @class NSBundle; @class NSButton; @class NSColor; @class NSColorList; @class NSDictionary; @class NSImage; @class NSMenuItemCell; @class NSMenuView; @class GSDrawTiles; /* Names for the component parts of a scroller, * allowing tiles and/or colors to be set for them. */ APPKIT_EXPORT NSString *GSScrollerDownArrow; APPKIT_EXPORT NSString *GSScrollerHorizontalKnob; APPKIT_EXPORT NSString *GSScrollerHorizontalSlot; APPKIT_EXPORT NSString *GSScrollerLeftArrow; APPKIT_EXPORT NSString *GSScrollerRightArrow; APPKIT_EXPORT NSString *GSScrollerUpArrow; APPKIT_EXPORT NSString *GSScrollerVerticalKnob; APPKIT_EXPORT NSString *GSScrollerVerticalSlot; /** * This defines how the values in a tile array should be used when * drawing a rectangle. Mostly this just effects the center, middle * image of the rectangle.
* FillStyleMatrix is provided for the use of theme editors wishing * to display the tile. */ typedef enum { GSThemeFillStyleNone, /** CM image is not drawn */ GSThemeFillStyleScale, /** CM image is scaled to fit */ GSThemeFillStyleRepeat, /** CM image is tiled from bottom left */ GSThemeFillStyleCenter, /** CM image is tiled from the center */ GSThemeFillStyleMatrix /** a matrix of nine separated images */ } GSThemeFillStyle; /** * This enumeration provides constants for informing drawing methods * what state a control is in (and consequently how the display element * being drawn should be presented). * NB. GSThemeNormalState must be 0 and GSThemeSelectedState must be the * last state, in order to allow code to iterate through all the states. */ typedef enum { GSThemeNormalState = 0, /** A control in its normal state */ GSThemeHighlightedState, /** A control which is highlighted */ GSThemeSelectedState /** A control which is selected */ } GSThemeControlState; /** Notification sent when a theme has just become active.
* The notification is posted by the -activate method.
* This is primarily for internal use by AppKit controls which * need to readjust how they are displayed when a new theme is in use. */ APPKIT_EXPORT NSString *GSThemeDidActivateNotification; /** Notification sent when a theme has just become inactive.
* The notification is posted by the -deactivate method.
* This is primarily for use by subclasses of GSTheme which need to perform * additional cleanup when the theme stops being used. */ APPKIT_EXPORT NSString *GSThemeDidDeactivateNotification; /** Notification sent when a theme is about to become active.
* The notification is posted by the -activate method.
* This is primarily for use by subclasses of GSTheme which need to perform * additional setup before the theme starts being used by the AppKit controls. */ APPKIT_EXPORT NSString *GSThemeWillActivateNotification; /** Notification sent when a theme is about to become inactive.
* The notification is posted by the -deactivate method.
* This allows code to make preparatory changes before the current theme * is deactivated. */ APPKIT_EXPORT NSString *GSThemeWillDeactivateNotification; /**

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.

*/ @interface GSTheme : NSObject { @private void *_reserved; } /** * Creates and displays a panel allowing selection of different themes * and display of the current theme inspector. */ + (void) orderFrontSharedThemePanel: (id)sender; /** * 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. */ + (void) setTheme: (GSTheme*)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. */ + (GSTheme*) theme; /** *

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. *

*/ - (void) activate; /** * Returns the names of the theme's authors. */ - (NSArray*) authors; /** * Return the bundle containing the resources used by the current theme. */ - (NSBundle*) bundle; /** * Returns the class used by the theme for loading color lists. The default * implementation returns the NSColorList class, but a subclass may override * this to return a color list class whose values change dynamically in * response to changes of a native theming API for instance.
* The class returned by this method should be NSColorList or one of its * subclasses. Subclasses should note that GSTheme will initialise the * instances of the class using the [NSColerList-initWithName:fromFile:] * method. */ - (Class) colorClass; /** * 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. */ - (NSColor*) colorNamed: (NSString*)aName state: (GSThemeControlState)elementState cache: (BOOL)useCache; /** * 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. */ - (NSColorList*) colors; /** *

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. *

*/ - (void) deactivate; /** * Returns the theme's icon. */ - (NSImage*) icon; /** * Returns the class used by the theme for loading images. The default * implementation returns the NSImage class, but a subclass may override * this to return an image class whose instances dynamically alter what * they draw in response to changes of a native theming API for instance.
* This method must return the NSImage class or one of its subclasses. * Subclass implementations should note that instances will be initialised * using the [NSImage-initWithContentsOfFile:] method and will use the * [NSImage-imageFileTypes] method to determine which image files can be * loaded. */ - (Class) imageClass; /** * 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. */ - (id) initWithBundle: (NSBundle*)bundle; /** *

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. * * * * */ - (NSDictionary*) infoDictionary; /** * Return the theme's name. */ - (NSString*) name; /** 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. */ - (NSString*) nameForElement: (id)anObject; /** Set the name of this theme ... used for testing by Thematic.app */ - (void) setName: (NSString*)aString; /** 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. */ - (void) setName: (NSString*)aString forElement: (id)anObject temporary: (BOOL)takeOwnership; /** *

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. *

*/ - (NSWindow*) themeInspector; /** * 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. */ - (GSDrawTiles*) tilesNamed: (NSString*)aName state: (GSThemeControlState)elementState cache: (BOOL)useCache; @end /** * Theme drawing methods */ @interface GSTheme (Drawing) /** * Draws a button frame and background (not its content) for the specified * cell and view. */ - (void) drawButton: (NSRect)frame in: (NSCell*)cell view: (NSView*)view style: (int)style state: (GSThemeControlState)state; /** * Amount by which the button is inset by the border. */ - (NSSize) buttonBorderForCell: (NSCell*)cell style: (int)style state: (GSThemeControlState)state; /** * Draws the indicator (normally a dotted rectangle) to show that * the view currently has keyboard focus. */ - (void) drawFocusFrame: (NSRect)frame view: (NSView*)view; /** * Draws the background of a window ... normally a simple fill with the * the window's background color. */ - (void) drawWindowBackground: (NSRect)frame view: (NSView*)view; /** * Draw a border of the specified border type. */ - (void) drawBorderType: (NSBorderType)aType frame: (NSRect)frame view: (NSView*)view; /** * Determine the size for the specified border type . */ - (NSSize) sizeForBorderType: (NSBorderType)aType; /** * Draw a border of the specified frame style. */ - (void) drawBorderForImageFrameStyle: (NSImageFrameStyle)frameStyle frame: (NSRect)frame view: (NSView*)view; /** * Determine the size for the specified frame style. */ - (NSSize) sizeForImageFrameStyle: (NSImageFrameStyle)frameStyle; /** * Methods for scroller theming. */ - (NSButtonCell*) cellForScrollerArrow: (NSScrollerArrow)part horizontal: (BOOL)horizontal; - (NSCell*) cellForScrollerKnob: (BOOL)horizontal; - (NSCell*) cellForScrollerKnobSlot: (BOOL)horizontal; - (float) defaultScrollerWidth; /** * Method for toolbar theming. */ - (void) drawToolbarRect: (NSRect)aRect frame: (NSRect)viewFrame borderMask: (unsigned int)borderMask; // Methods to deal with steppers.. /** * Draw light colored stepper using the border and clip rects */ - (NSRect) drawStepperLightButton: (NSRect) border :(NSRect) clip; /** * Draw normal stepper up button. */ - (void) drawStepperUpButton: (NSRect) aRect; /** * Draw highlighted up stepper button. */ - (void) drawStepperHighlightUpButton: (NSRect) aRect; /** * Draw down button for stepper */ - (void) drawStepperDownButton: (NSRect) aRect; /** * Draw highlighted stepper down button */ - (void) drawStepperHighlightDownButton: (NSRect) aRect; /** * In some themes it may be necessary to override the drawing * of an image a button cell and replace it with a rendered * version (from the native theme). */ - (void) drawImage: (NSImage *)image inButtonCell: (NSButtonCell *) cell withFrame: (NSRect) aRect position: (NSPoint) position; @end /** * Helper functions for drawing standard items. */ @interface GSTheme (MidLevelDrawing) /** Draw a standard button */ - (NSRect) drawButton: (NSRect)border withClip: (NSRect)clip; /** Draw a dark bezel border */ - (NSRect) drawDarkBezel: (NSRect)border withClip: (NSRect)clip; /** Draw a "dark" button border (used in tableviews) */ - (NSRect) drawDarkButton: (NSRect)border withClip: (NSRect)clip; /** Draw a frame photo border. Used in NSImageView. */ - (NSRect) drawFramePhoto: (NSRect)border withClip: (NSRect)clip; /** Draw a gradient border. */ - (NSRect) drawGradientBorder: (NSGradientType)gradientType inRect: (NSRect)border withClip: (NSRect)clip; /** Draw a grey bezel border */ - (NSRect) drawGrayBezel: (NSRect)border withClip: (NSRect)clip; /** Draw a groove border */ - (NSRect) drawGroove: (NSRect)border withClip: (NSRect)clip; /** Draw a light bezel border */ - (NSRect) drawLightBezel: (NSRect)border withClip: (NSRect)clip; /** Draw a white bezel border */ - (NSRect) drawWhiteBezel: (NSRect)border withClip: (NSRect)clip; @end /** * Low level drawiong methods ... themes may use these for drawing, * but should not normally override them. */ @interface GSTheme (LowLevelDrawing) /** * 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. */ - (void) fillHorizontalRect: (NSRect)rect withImage: (NSImage*)image fromRect: (NSRect)source flipped: (BOOL)flipped; /** * 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. */ - (void) fillRect: (NSRect)rect withRepeatedImage: (NSImage*)image fromRect: (NSRect)source center: (BOOL)center; /** * 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). */ - (NSRect) fillRect: (NSRect)rect withTiles: (GSDrawTiles*)tiles background: (NSColor*)color fillStyle: (GSThemeFillStyle)style; /** * 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. */ - (void) fillVerticalRect: (NSRect)rect withImage: (NSImage*)image fromRect: (NSRect)source flipped: (BOOL)flipped; @end #endif /* OS_API_VERSION */ #endif /* _GNUstep_H_GSTheme */