IlvPalette Class Reference

Resource class. More...

#include <ilviews/base/resource.h>

Inheritance diagram for IlvPalette:

Classes
class	Builder
	IlvPalette builder. More...
class	Changer
	IlvPalette changer. More...

Public Member Functions
	IlvPalette (IlvDisplay *display)
	Initializes a new IlvPalette that is not shared. More...
	IlvPalette (IlvDisplay *display, IlvColor *background, IlvColor *foreground, IlvFont *font, IlvPattern *pattern)
	Initializes a new IlvPalette that is not shared, with the specified parameters. More...
	IlvPalette (IlvPalette const *palette)
	Initializes a new IlvPalette that is not shared, as a copy of another palette. More...
	IlvPalette (IlvPalette const &palette)
	Initializes a new IlvPalette that is not shared as a copy of another palette. More...
IlvIntensity	getAlpha () const
	Gets the alpha value. More...
IlvAntialiasingMode	getAntialiasingMode () const
	Gets the anti-aliasing mode. More...
IlvArcMode	getArcMode () const
	Gets the arc mode. More...
IlvColor *	getBackground () const
	Gets the background color. More...
IlvColorPattern *	getColorPattern () const
	Gets the color pattern. More...
IlvFillRule	getFillRule () const
	Gets the fill rule. More...
IlvFillStyle	getFillStyle () const
	Gets the fill style. More...
IlvFont *	getFont () const
	Gets the font. More...
IlvColor *	getForeground () const
	Gets the foreground color. More...
IlvGradientPattern *	getGradientPattern () const
	Gets the gradient pattern. More...
IlvLineStyle *	getLineStyle () const
	Gets the line style. More...
IlUShort	getLineWidth () const
	Gets the line width. More...
IlvDrawMode	getMode () const
	Gets the drawing mode. More...
IlBoolean	getOverwrite () const
	Gets the overwrite flag. More...
IlvPattern *	getPattern () const
	Gets the pattern. More...
void	invert ()
	Swaps the foreground and background of the palette. More...
void	setAlpha (IlvIntensity alpha)
	Sets the alpha value. More...
void	setAntialiasingMode (IlvAntialiasingMode antialias)
	Sets the anti-aliasing mode. More...
void	setArcMode (IlvArcMode arcMode)
	Sets the arc mode. More...
void	setBackground (IlvColor *color)
	Sets the background color. More...
void	setClip (const IlvRect *rect=0) const
	Set or reset clipping rectangle. More...
void	setClip (const IlvRegion *clip) const
	Set clipping region. More...
void	setColorPattern (IlvColorPattern *pattern)
	Sets the color pattern. More...
void	setFillRule (IlvFillRule fillRule)
	Sets the fill rule. More...
void	setFillStyle (IlvFillStyle fillStyle)
	Sets the fill style. More...
void	setFont (IlvFont *font)
	Sets the font. More...
void	setForeground (IlvColor *color)
	Sets the foreground color. More...
void	setGradientPattern (IlvGradientPattern *pattern)
	Sets the gradient pattern. More...
void	setLineStyle (IlvLineStyle *style, IlUShort width)
	Sets the line style and width. More...
void	setLineStyle (IlvLineStyle *style)
	Sets the line style. More...
void	setLineWidth (IlUShort width)
	Sets the line width. More...
void	setMode (IlvDrawMode drawMode) const
	Sets the drawing mode. More...
void	setOverwrite (IlBoolean over) const
	Sets the overwrite flag. More...
void	setPattern (IlvPattern *pattern)
	Sets the pattern. More...
virtual void	unLock ()
	Unlocks the resource. More...
Public Member Functions inherited from IlvResource
IlvDisplay *	getDisplay () const
	Gets the IlvDisplay instance. More...
const char *	getName () const
	Gets the resource name. More...
void	lock ()
	Locks the resource. More...
virtual void	setName (const char *name)
	Sets the name of the resource. More...

Friends
class	IlvDisplay

Detailed Description

Resource class.

Library: xviews or winviews or mviews (mutually exclusive)
IlvPalette groups together the graphic resources used in drawing primitives:

• Background color: this IlvColor is used as a second color when filling a shape with patterns. It is also used for filling the background of character strings when they are drawn with the member function IlvPort::drawIString().
  If the use of a palette does not require a background color, you may use IlvDisplay::defaultBackground().
• Foreground color: this IlvColor is used for drawing outline shapes (dot, line, rectangle, polyline, arc, curve, ...) and character strings. For example, IlvPort::drawRectangle(), IlvPort::drawString().
  It is also used when filling simple shapes that have no outline. For example, IlvPort::fillRectangle().
  If the foreground color is not particularly important, you can avoid resource allocation and use the default value returned by the member function IlvDisplay::defaultForeground().
• Pattern: this graphic resource is represented by the class IlvPattern. We are referring to the pattern used to fill surfaces when the fill mode is IlvFillPattern or IlvFillMaskPattern. This IlvPattern can be created by the user or returned by specific member functions of the IlvDisplay class, which offers sixteen ready-to-use patterns.
  To quickly get a valid value, you can access the solid pattern by means of the returned value of the IlvDisplay::defaultPattern() member function.
• Color pattern: this graphic resource is represented by the class IlvColorPattern. We use the expression "color pattern" for the colored pattern used to fill shapes when the fill mode is IlvFillColorPattern. The default value for the color pattern is 0, indicating that no color pattern is to be used.
• Font: this graphic resource is represented by the class IlvFont. It is used when drawing text. Fonts are obtained by means of IlvDisplay member functions that return a valid font object depending on user-required characteristics.
• Line style: this resource is represented by the class IlvLineStyle. The line style and width define the exact visible aspect of all lines, polylines, and spline drawings.
  You can create your own line styles by requesting IlvLineStyle resource objects from your IlvDisplay object, and specifying the way that dashes are to be drawn.
• Line width: The line width is an unsigned short integer. Zero happens to be a perfectly valid value, producing a line whose width is such that it can be drawn as rapidly as possible.
• Fill style: The fill style indicates the way in which patterns are used to fill shapes. There are three possible cases, which are represented in the IlvFillStyle enumeration type:
  • IlvFillPattern: A shape is filled by being copied with the chosen pattern. Graphic objects have a pattern property referring to an object of the IlvPattern class. To fill a shape with a given pattern, each '0' pixel in the relevant IlvPattern object produces a colored pixel with the current background color, and each '1' pixel in the IlvPattern object produces a colored pixel with the current foreground color. This is the default value of the fill-style property of an IlvPalette object.
  • IlvFillMaskPattern: This is similar to the IlvFillPattern style except that '0' pixels in the relevant IlvPattern object have no effect on the corresponding pixels in the destination port. That is, the drawing can be thought of as masking its destination.
  • IlvFillColorPattern: In this case, the pattern used to fill a shape is indicated, not by the pattern property of this IlvPalette object, but rather by its colored pattern property. It is used when you wish to fill a region with a full-color pattern, that is, an actual object of the IlvColorPattern class. The pattern property plays no role in the case of this filling mode.

• Arc mode: The arc mode indicates the way in which filled arcs are to be drawn. It is represented by the IlvArcMode enumeration type and has two possible values:

  • IlvArcPie: The arc is closed by adding two lines, from the center of the complete circle to the start and end points of the arc.
    This is the default mode.
  • IlvArcChord: The arc is closed by adding a line from the start point to the end point.
  

  
  - Arc Modes -

• Fill rule: The fill rule indicates which points are to be considered as inside a polygon that is to be filled, depending on the count of crossing segments that define the shape of the area to be filled. It is represented by the IlvFillRule enumeration type and has two possible values:

  • IlvEvenOddRule: According to this rule, in the case of the complex polygon shown below, the central area of the star is not considered to lie inside the polygon, and therefore is not filled. This is the default value.
  • IlvWindingRule: According to this rule, the central area of the star is considered to lie inside the polygon, and therefore is filled.
  

  
  - IlvFillRule -

• Draw mode: The draw mode indicates a bitwise operation to be performed with pixel values on the destination port. Most draw modes are only meaningful when drawing in monochrome color model. The IlvModeXor value may be used for temporary drawing.
  Draw modes are specified with the IlvDrawMode enumeration type:
  • IlvModeSet: The resulting pixel is a copy of the source pixel.
  • IlvModeOr: The resulting pixel is the result of an OR operation upon the source and destination pixels.
  • IlvModeAnd: The resulting pixel is the result of an AND operation upon the source and destination pixels.
  • IlvModeXor: The resulting pixel is the result of an XOR (exclusive or) operation upon the source and destination pixels. This mode is interesting in that it can be used a second time to delete a drawing.
  • IlvModeNot: The resulting pixel is the result of the NOT operation upon the destination pixel. The source pixel value is not used.
  • IlvModeInvert: The resulting pixel is the result of a NOT operation upon the source pixel.
  • IlvModeNotOr: The resulting pixel is the result of a NOT OR operation upon the source and destination pixels.
  • IlvModeNotAnd: The resulting pixel is the result of a NOT AND operation upon the source and destination pixels.
  • IlvModeNotXor: The resulting pixel is the result of a NOT XOR operation upon the source and destination pixels. When you draw the same thing twice with IlvModeNotXor set, the drawing disappears.

There are two ways of creating a palette:

• Use a shared palette. This is by far the most common usage. A call to IlvDisplay::getPalette() provides you with a palette matching your description. If the IlvDisplay finds a match in the in the list of existing palettes, it is returned, otherwise a new one is created.
  A shared palette has potentially several owners so it must not be deleted. Instead, it should be locked when you obtain it and unlocked when you do not need it any longer. See lock() and unLock().
  Similarily, a shared palette should not be modified because it would affect other owners using it.
• Create a non-shared palette. This is done by using the new operator and the IlvPalette constructor. Use a non-shared palette when you need to modify it frequently or when you do not want to share it. A non-shared palette still uses shared resources such as IlvFont, IlvColor, and so on, which are locked and unlocked in the same way as shared palettes.
  If you decide to build an IlvPalette object in this way, you have the responsibility of deleting it explicitly when it is no longer needed because the lock() and unLock() mechanisms are not supported by non-shared palettes (unLock() never deletes a non-shared palette).

See also

IlvDisplay::getPalette(), IlvColor, IlvLineStyle, IlvPattern.

Constructor & Destructor Documentation

IlvPalette() [1/4]

IlvPalette::IlvPalette

(

IlvDisplay *

display

)

Initializes a new IlvPalette that is not shared.

The new palette is initialized with all the default values provided by the display.

Parameters

display

The display instance.

IlvPalette() [2/4]

IlvPalette::IlvPalette	(	IlvDisplay *	display,
		IlvColor *	background,
		IlvColor *	foreground,
		IlvFont *	font,
		IlvPattern *	pattern
	)

Initializes a new IlvPalette that is not shared, with the specified parameters.

Parameters

display	The display instance.
background	The background color of this palette.
foreground	The foreground color of this palette.
font	The font of this palette.
pattern	The fill pattern color of this palette.

IlvPalette() [3/4]

IlvPalette::IlvPalette

(

IlvPalette const *

palette

)

Initializes a new IlvPalette that is not shared, as a copy of another palette.

Constructor.

Parameters

palette

A pointer to the palette that is copied.

IlvPalette() [4/4]

IlvPalette::IlvPalette

(

IlvPalette const &

palette

)

Initializes a new IlvPalette that is not shared as a copy of another palette.

Parameters

palette

The palette that is copied.

Member Function Documentation

getAlpha()

IlvIntensity IlvPalette::getAlpha

(

)

const

Gets the alpha value.

The alpha value is the amount of opacity that will be used when drawing with this palette. A value of IlvFullIntensity means that the drawing will be opaque. A value of 0 means that the drawing will be completely transparent. When drawing into an IlvPort object, the alpha value of the palette will be composed with the alpha value of the port.

Returns

The alpha value of the palette.

getAntialiasingMode()

IlvAntialiasingMode IlvPalette::getAntialiasingMode

(

)

const

Gets the anti-aliasing mode.

Returns

The anti-aliasing mode of the palette.

getArcMode()

IlvArcMode IlvPalette::getArcMode

(

)

const

Gets the arc mode.

Returns

The arc mode attribute of the palette.

getBackground()

IlvColor* IlvPalette::getBackground

(

)

const

Gets the background color.

Retrieves the background color of the palette. This resource should never be deleted. If you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The background color of the palette.

getColorPattern()

IlvColorPattern* IlvPalette::getColorPattern

(

)

const

Gets the color pattern.

Retrieves the color pattern of the palette. This resource should never be deleted; if you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The color pattern of the palette.

getFillRule()

IlvFillRule IlvPalette::getFillRule

(

)

const

Gets the fill rule.

Returns

The fill rule attribute of the palette.

getFillStyle()

IlvFillStyle IlvPalette::getFillStyle

(

)

const

Gets the fill style.

Returns

The line width attribute of the palette.

getFont()

IlvFont* IlvPalette::getFont

(

)

const

Gets the font.

Retrieves the font of the palette. This resource should never be deleted; if you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The font of the palette.

getForeground()

IlvColor* IlvPalette::getForeground

(

)

const

Gets the foreground color.

Retrieves the foreground color of the palette. This resource should never be deleted; if you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The foreground color of the palette.

getGradientPattern()

IlvGradientPattern* IlvPalette::getGradientPattern

(

)

const

Gets the gradient pattern.

Retrieves the gradient pattern of the palette. This resource should never be deleted; if you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The color pattern of the palette.

getLineStyle()

IlvLineStyle* IlvPalette::getLineStyle

(

)

const

Gets the line style.

Retrieves the line style of the palette. This resource should never be deleted; if you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The line style of the palette.

getLineWidth()

IlUShort IlvPalette::getLineWidth

(

)

const

Gets the line width.

Returns

The line width attribute of the palette.

getMode()

IlvDrawMode IlvPalette::getMode

(

)

const

Gets the drawing mode.

Returns

The current drawing mode of the palette.

getOverwrite()

IlBoolean IlvPalette::getOverwrite

(

)

const

Gets the overwrite flag.

Returns

Indicates whether or not the drawing functions that use this palette draw on top of or under the windows.

getPattern()

IlvPattern* IlvPalette::getPattern

(

)

const

Gets the pattern.

Retrieves the pattern of the palette. This resource should never be deleted; if you want to use it in a context different from this palette, you should consider using lock() and unLock() on the resource.

Returns

The pattern of the palette.

invert()

void IlvPalette::invert

(

)

Swaps the foreground and background of the palette.

Swaps the foreground and the background color of this IlvPalette object.

setAlpha()

void IlvPalette::setAlpha

(

IlvIntensity

alpha

)

Sets the alpha value.

Parameters

alpha

The new alpha value of the palette.

setAntialiasingMode()

void IlvPalette::setAntialiasingMode

(

IlvAntialiasingMode

antialias

)

Sets the anti-aliasing mode.

Parameters

antialias

The new anti-aliasing mode of the palette.

setArcMode()

void IlvPalette::setArcMode

(

IlvArcMode

arcMode

)

Sets the arc mode.

Sets arcMode as the arc mode attribute of the palette.

Parameters

arcMode

The arc mode to set.

setBackground()

void IlvPalette::setBackground

(

IlvColor *

color

)

Sets the background color.

Sets the background color of the palette. The palette calls lock() on the resource provided as argument. Then the palette calls unLock() on the old resource to release a reference to it.

Parameters

color

The new background color.

setClip() [1/2]

void IlvPalette::setClip

(

const IlvRect *

rect = 0

)

const

Set or reset clipping rectangle.

This member function forces all drawing operations that are done with this IlvPalette to be clipped in the rectangle rect. If no value is given, then 0 is assumed and no clipping takes place anymore. You should always reset the clipping region to none (that is, call the member function setClip() with no parameter) after it has been used, because clipping is not considered as a persistent attribute of the palette (two palettes using exactly the same resources but different clipping regions are considered identical).

Parameters

rect	The rectangle on which clipping is to occur, or 0 to reset clipping.

setClip() [2/2]

void IlvPalette::setClip

(

const IlvRegion *

clip

)

const

Set clipping region.

This member function forces all drawing operations that are done with this IlvPalette to be clipped in the region clip. It has the same effect as the first setClip() method, except that the clipping now takes place on a real region.

Parameters

clip	The region on which clipping is to occur.

setColorPattern()

void IlvPalette::setColorPattern

(

IlvColorPattern *

pattern

)

Sets the color pattern.

Sets the color pattern of the palette. The palette calls lock() on the resource provided as argument. Then the palette calls unLock() on the old resource to release a reference to it.

Parameters

pattern

The new color pattern.

setFillRule()

void IlvPalette::setFillRule

(

IlvFillRule

fillRule

)

Sets the fill rule.

Sets fillRule as the fill rule attribute of the palette.

Parameters

fillRule

The fill rule to set.

setFillStyle()

void IlvPalette::setFillStyle

(

IlvFillStyle

fillStyle

)

Sets the fill style.

Sets fillStyle as the fill style attribute of the palette.

Parameters

fillStyle

The fill style to set.

setFont()

void IlvPalette::setFont

(

IlvFont *

font

)

Sets the font.

Sets the font of the palette. The palette calls lock() on the resource provided as argument. Then the palette calls unLock() on the old resource to release a reference to it.

Parameters

font	The new font.

setForeground()

void IlvPalette::setForeground

(

IlvColor *

color

)

Sets the foreground color.

Sets the foreground color of the palette. The palette calls lock() on the resource provided as argument. Then the palette calls unLock() on the old resource to release a reference to it.

Parameters

color

The new foreground color.

setGradientPattern()

void IlvPalette::setGradientPattern

(

IlvGradientPattern *

pattern

)

Sets the gradient pattern.

Sets the gradient pattern of the palette. The palette calls lock() on the resource provided as argument. Then the palette calls unLock() on the old resource to release a reference to it.

Parameters

pattern

The new color pattern.

setLineStyle() [1/2]

void IlvPalette::setLineStyle	(	IlvLineStyle *	style,
		IlUShort	width
	)

Sets the line style and width.

Sets style as the line style resource of the palette and width as the line width attribute. The palette calls lock() on style, then the palette calls unLock() on the old line style resource to release a reference to it.

Parameters

style	The line style to set.
width	The line width to set.

setLineStyle() [2/2]

void IlvPalette::setLineStyle

(

IlvLineStyle *

style

)

Sets the line style.

Sets style as the line style resource of the palette. The palette calls lock() on style, then the palette calls unLock() on the old line style resource to release a reference to it.

Parameters

style

The line style to set.

setLineWidth()

void IlvPalette::setLineWidth

(

IlUShort

width

)

Sets the line width.

Sets width as the line width attribute of the palette.

Parameters

width

The line width to set.

setMode()

void IlvPalette::setMode

(

IlvDrawMode

drawMode

)

const

Sets the drawing mode.

Sets the drawing mode of this palette to drawMode.

Parameters

drawMode

The drawing mode to set.

setOverwrite()

void IlvPalette::setOverwrite

(

IlBoolean

over

)

const

Sets the overwrite flag.

Modifies the way the drawing member functions of the IlvDisplay class operate when drawing on the root port. If the over parameter is set to IlFalse, the drawing operations are hidden by the windows stored on the top window. If the parameter is set to IlTrue, the drawing operations are performed on top of every window present on the screen, just as if the windows were part of the root window.

Parameters

over	The new overwrite flag value.

setPattern()

void IlvPalette::setPattern

(

IlvPattern *

pattern

)

Sets the pattern.

Sets the pattern of the palette. The palette calls lock() on the resource provided as argument. Then the palette calls unLock() on the old resource to release a reference to it.

Parameters

pattern

The new pattern.

unLock()

virtual void IlvPalette::unLock ( )

virtual

Unlocks the resource.

This function decrements the reference count of the resource, and deletes it if this count becomes 0. Resource management is closely concerned with the way resources are locked and unlocked. Whenever you need a specific resource in one of your persistent objects, you should use this mechanism to make sure that it will stay safe within your IlvDisplay instance. If your application needs more than one instance of IlvDisplay, you have to create resources within each environment, since resources cannot be shared between the different IlvDisplay contexts.

Reimplemented from IlvResource.