IlvPalette Class Reference

Resource class. More...

#include <ilviews/base/resource.h>

Inheritance diagram for IlvPalette:

List of all members.

Public Member Functions
	IlvPalette (IlvPalette const &palette)
	Copy Constructor.
	IlvPalette (IlvPalette const *palette)
	Constructor.
	IlvPalette (IlvDisplay *display, IlvColor *background, IlvColor *foreground, IlvFont *font, IlvPattern *pattern)
	Constructor.
	IlvPalette (IlvDisplay *display)
	Constructor.
IlvIntensity	getAlpha () const
	Gets the alpha value.
IlvAntialiasingMode	getAntialiasingMode () const
	Gets the anti-aliasing mode.
IlvArcMode	getArcMode () const
	Gets the arc mode.
IlvColor *	getBackground () const
	Gets the background color.
IlvColorPattern *	getColorPattern () const
	Gets the color pattern.
IlvFillRule	getFillRule () const
	Gets the fill rule.
IlvFillStyle	getFillStyle () const
	Gets the fill style.
IlvFont *	getFont () const
	Gets the font.
IlvColor *	getForeground () const
	Gets the foreground color.
IlvGradientPattern *	getGradientPattern () const
	Gets the gradient pattern.
IlvLineStyle *	getLineStyle () const
	Gets the line style.
IlUShort	getLineWidth () const
	Gets the line width.
IlvDrawMode	getMode () const
	Gets the drawing mode.
IlBoolean	getOverwrite () const
	Gets the overwrite flag.
IlvPattern *	getPattern () const
	Gets the pattern.
void	invert ()
	Swaps the foreground and background of the palette.
void	setAlpha (IlvIntensity alpha)
	Sets the alpha value.
void	setAntialiasingMode (IlvAntialiasingMode antialias)
	Sets the anti-aliasing mode.
void	setArcMode (IlvArcMode arcMode)
	Sets the arc mode.
void	setBackground (IlvColor *color)
	Sets the background color.
void	setClip (const IlvRegion *clip) const
	Set clipping region.
void	setClip (const IlvRect *rect=0) const
	Set or reset clipping rectangle.
void	setColorPattern (IlvColorPattern *pattern)
	Sets the color pattern.
void	setFillRule (IlvFillRule fillRule)
	Sets the fill rule.
void	setFillStyle (IlvFillStyle fillStyle)
	Sets the fill style.
void	setFont (IlvFont *font)
	Sets the font.
void	setForeground (IlvColor *color)
	Sets the foreground color.
void	setGradientPattern (IlvGradientPattern *pattern)
	Sets the gradient pattern.
void	setLineStyle (IlvLineStyle *style)
	Sets the line style.
void	setLineStyle (IlvLineStyle *style, IlUShort width)
	Sets the line style and width.
void	setLineWidth (IlUShort width)
	Sets the line width.
void	setMode (IlvDrawMode drawMode) const
	Sets the drawing mode.
void	setOverwrite (IlBoolean over) const
	Sets the overwrite flag.
void	setPattern (IlvPattern *pattern)
	Sets the pattern.
virtual void	unLock ()
	Unlocks the resource.
Friends
class	IlvDisplay

---

Detailed Description

Resource class.

Library: display

Groups together the current drawing resources, namely:

• Background color: The background color is used as a second color when filling with patterns. This color is also used for the background of character strings when they are drawn with the member function IlvPort::drawIString. Background color is also an IlvColor instance. The IlvDisplay::defaultBackground member function gives you a valid internal value.
• Foreground color: The foreground color is used for drawing such things as dots, lines, and polylines. The same color is used to display character strings. It is an IlvColor instance that can be created with specific IlvDisplay member functions. If the exact color is not particularly important, you can avoid resource allocation and use the default value returned by the member function IlvDisplay::defaultForeground.

• Pattern: We are referring to the pattern used to fill surfaces when the fill mode is IlvFillPattern or IlvFillMaskPattern. Its value is an instance of IlvPattern, whether 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: 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 IlvNil, indicating that no color pattern is to be used.
• Font: This is the font 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: 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. There are two possible cases that are taken care of by the IlvArcMode enumeration type:

  • 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. There are two possible ways that this consideration is made. These two ways are enumerated in IlvFillRule:

  • 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 the operation to be performed upon pixels when they are sent to the destination port. The operation is the one that would affect the destination pixel value when the source pixel value is to be drawn at that place. Except for the IlvModeXor value, used in temporary drawing, these modes produce no significant graphic result when drawing in color. There are several possible cases for the draw mode. They are handled by 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: The more typical means is to ask the IlvDisplay object to supply you with the palette you want. If the palette already exists, it is given.

• Create a nonshared palette: Use a nonshared palette when you need to modify it frequently, or when you do not want to share it. A nonshared palette uses shared resources such as IlvFont, IlvColor, and so on, which are locked and unlocked in the same way as for 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 nonshared palettes (unLock never deletes a nonshared palette).

See also:

IlvDisplay::getPalette, IlvColor, IlvLineStyle, IlvPattern.

---

Constructor & Destructor Documentation

IlvPalette::IlvPalette

(

IlvDisplay *

display

)

Constructor.

Creates a nonshared palette. The new palette is initialized with all the default values offered by the display.

Parameters:

display

The display instance.

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

Constructor.

Creates a nonshared palette 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::IlvPalette

(

IlvPalette const *

palette

)

Constructor.

Creates a nonshared palette that is a copy of the palette palette.

Parameters:

palette

An existing palette.

IlvPalette::IlvPalette

(

IlvPalette const &

palette

)

Copy Constructor.

Creates a nonshared palette that is a copy of the palette palette.

Parameters:

palette

An existing palette.

---

Member Function Documentation

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.

IlvAntialiasingMode IlvPalette::getAntialiasingMode

(

)

const

Gets the anti-aliasing mode.

Returns:

The anti-aliasing mode of the palette.

IlvArcMode IlvPalette::getArcMode

(

)

const

Gets the arc mode.

Returns:

The arc mode attribute of the palette.

IlvColor* IlvPalette::getBackground

(

)

const

Gets the background color.

Retrieves the background color IlvResource 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.

IlvColorPattern* IlvPalette::getColorPattern

(

)

const

Gets the color pattern.

Retrieves the color pattern IlvResource 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.

IlvFillRule IlvPalette::getFillRule

(

)

const

Gets the fill rule.

Returns:

The fill rule attribute of the palette.

IlvFillStyle IlvPalette::getFillStyle

(

)

const

Gets the fill style.

Returns:

The line width attribute of the palette.

IlvFont* IlvPalette::getFont

(

)

const

Gets the font.

Retrieves the font IlvResource 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.

IlvColor* IlvPalette::getForeground

(

)

const

Gets the foreground color.

Retrieves the foreground color IlvResource 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.

IlvGradientPattern* IlvPalette::getGradientPattern

(

)

const

Gets the gradient pattern.

Retrieves the gradient pattern IlvResource 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.

IlvLineStyle* IlvPalette::getLineStyle

(

)

const

Gets the line style.

Retrieves the line style IlvResource 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.

IlUShort IlvPalette::getLineWidth

(

)

const

Gets the line width.

Returns:

The line width attribute of the palette.

IlvDrawMode IlvPalette::getMode

(

)

const

Gets the drawing mode.

Returns:

The current drawing mode of the palette.

IlBoolean IlvPalette::getOverwrite

(

)

const

Gets the overwrite flag.

Returns:

The Boolean flag that indicates whether or not the drawing functions that use this palette draw on top of or under the windows.

IlvPattern* IlvPalette::getPattern

(

)

const

Gets the pattern.

Retrieves the pattern IlvResource 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.

void IlvPalette::invert

(

)

Swaps the foreground and background of the palette.

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

void IlvPalette::setAlpha

(

IlvIntensity

alpha

)

Sets the alpha value.

Parameters:

alpha

The new alpha value of the palette.

void IlvPalette::setAntialiasingMode

(

IlvAntialiasingMode

antialias

)

Sets the anti-aliasing mode.

Parameters:

antialias

The new anti-aliasing mode of the palette.

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.

void IlvPalette::setBackground

(

IlvColor *

color

)

Sets the background color.

Sets the background color IlvResource 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.

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 clip region. 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.

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 clip rectangle. 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.

void IlvPalette::setColorPattern

(

IlvColorPattern *

pattern

)

Sets the color pattern.

Sets the color pattern IlvResource 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.

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.

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.

void IlvPalette::setFont

(

IlvFont *

font

)

Sets the font.

Sets the font IlvResource 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.

void IlvPalette::setForeground

(

IlvColor *

color

)

Sets the foreground color.

Sets the foreground color IlvResource 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.

void IlvPalette::setGradientPattern

(

IlvGradientPattern *

pattern

)

Sets the gradient pattern.

Sets the gradient pattern IlvResource 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.

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.

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.

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.

void IlvPalette::setMode

(

IlvDrawMode

drawMode

)

const

Sets the drawing mode.

Sets the drawing mode of this palette to the IlvDrawMode drawMode.

Parameters:

drawMode

The drawing mode to set.

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

A Boolean value to set the overwrite flag.

void IlvPalette::setPattern

(

IlvPattern *

pattern

)

Sets the pattern.

Sets the pattern IlvResource 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.

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.