1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HTML>
<HEAD>
<TITLE>Crystal Space: CSWS Concepts</TITLE>
<META NAME="description" CONTENT="Crystal Space: CSWS Concepts">
<META NAME="keywords" CONTENT="Crystal Space: CSWS Concepts">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC312"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_143.html#SEC311"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_145.html#SEC316"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_142.html#SEC310"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_143.html#SEC311"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_149.html#SEC326"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<HR SIZE=1>
<H3> 6.6.1 Concepts </H3>
<!--docid::SEC312::-->
<P>
There is nothing new in CSWS regarding the window system. All base
conceptions for building such an system were invented long ago, at least when
first X-Windows system was built, or even earlier.
</P><P>
The system is event-based, events are generated by hardware (mouse, keyboard)
or software (components can send messages to each other). Event-system is
system-dependent as well as graphics subsystem. They were developed first as
part of Crystal Space itself, then some modifications were made to better fit
CSWS requirements. CSWS itself is completely system-independent,
i.e. you can easily develop programs that will compile and work with no
problems under any system supported by Crystal Space.
</P><P>
Since Crystal Space always uses buffered visuals, the screen repainting is
always done on the invisible page. This means flickering on redraw is almost
impossible in CSWS, while it is common on many GUIs with
poorly-written programs. If visual has more than one <EM>back-buffer</EM> (as
with the OS/2 DIVE canvas plugin), the image is automatically
re-syncronized on all back-buffers, but this slows down the refresh. Thus if
your program is mostly using the windowing system it is advised that you
disable double-buffering before using the windowing system.
</P><P>
Another Crystal Space-specific feature is the division of event processing into
<EM>frames</EM>. Since Crystal Space is a animation engine it operates in terms
of frames, thus when the frame begins, all pending events in event queue are
processed, then all invalid components are redrawn, and at last the image is
blitted onto the screen. Note that CSWS shares the global event queue
used by all plug-ins (and strictly speaking CSWS behaves like a plug-in
from system driver's point of view). This means other plug-ins can "steal"
events from the windowing system (if they improperly designed).
</P><P>
<A NAME="SEC313"></A>
<H3> Basic Concepts </H3>
<!--docid::SEC313::-->
<P>
This section provides an overview of the basic concepts of coordinate system
and color palette. These discussions provide a solid foundation for
subsequent discussions.
</P><P>
<A NAME="SEC314"></A>
<H4> Coordinate System </H4>
<!--docid::SEC314::-->
<P>
The coordinate system is based on most-used (yet undesirable) system where
top-left corner is (0,0) and bottom-right corner is (<VAR>width</VAR>,
<VAR>height</VAR>). It would be better to use the more desirable coordinate system
which is used, for example in OS/2 and OpenGL, but most programmers are
already familiar with the the less disirable one.
</P><P>
Most CSWS functions works with rectangles (`<SAMP>csRect</SAMP>' class). The
`<SAMP>csRect</SAMP>' class has four data fields: `<SAMP>xmin</SAMP>', `<SAMP>xmax</SAMP>',
`<SAMP>ymin</SAMP>', and `<SAMP>ymax</SAMP>', which are self-explanatory. Here is a example
of the rectangle (<VAR>xmin</VAR> = 0, <VAR>ymin</VAR> = 0, <VAR>xmax</VAR> = 3, <VAR>ymax</VAR> =
2):
</P><P>
<TABLE><tr><td> </td><td class=example><pre> 0 1 2 3 4 ...
| | | | | |
0 --##########--+--+--
#//|//|//# | |
1 --#--+--+--#--+--+--
#//|//|//# | |
2 --##########--+--+--
| | | | | |
3 --+--+--+--+--+--+--
| | | | | |
...--+--+--+--+--+--+--
</pre></td></tr></table></P><P>
Vertical line `<SAMP>X = 3</SAMP>' and horizontal line `<SAMP>Y = 2</SAMP>' do <EM>not</EM>
belong to the rectangle. The hashed pixels belong to the rectangle. So, if
you have two windows: (0, 0) - (3, 2) and (3, 0) - (6, 2) they do <EM>not</EM>
overlap.
</P><P>
<A NAME="SEC315"></A>
<H4> Palette </H4>
<!--docid::SEC315::-->
<P>
CSWS has been designed to operate transparently and independent of screen
geometry or number of colors. To allow normal operation in different pixel
format conditions colors are kept in a dynamically-built table which is
referenced through indexes in that table. To allow different palettes for
windowing system each component does not use colors directly when drawing,
instead each component has a pointer to a table which contains color values.
So, for example, a component can have a palette which's first element is used
as background color, second is used to display text in window and so on. By
changing only the palette table we can change at once how all these components
are looking.
</P><P>
There are a number of pre-defined colors with names of the form
`<SAMP>cs_Color_<VAR>XXX</VAR></SAMP>', for example `<SAMP>cs_Color_Black</SAMP>',
`<SAMP>cs_Color_White</SAMP>' etc. There are some colors with varying intensities
which are named `<SAMP>cs_Color_<VAR>YYY</VAR>_<VAR>Z</VAR></SAMP>'; where <VAR>YYY</VAR> is something
like `<SAMP>Blue</SAMP>', `<SAMP>Red</SAMP>', and so on; and the <VAR>Z</VAR> suffix stands for the
intensity---`<SAMP>D</SAMP>' for dark, `<SAMP>M</SAMP>' for medium, `<SAMP>L</SAMP>' for light.
</P><P>
There are a small number of pre-defined colors. What if you want to use a
color that is not predefined as a screen-depth-independent constant? The
answer is, you can use <CODE>csApp::FindColor()</CODE> to find a integer
representation of the color (which is very hardware dependent) given the
<<VAR>r</VAR>,<VAR>g</VAR>,<VAR>b</VAR>> components of the color (where <VAR>r</VAR>,
<VAR>g</VAR>, and <VAR>b</VAR> are in the range 0-255). Then you use the returned color
identifier in the same places where a `<SAMP>cs_Color_<VAR>XXX</VAR></SAMP>' value is
expected.
</P><P>
Note that the <CODE>FindColor()</CODE> method never fails: it always returns the
nearest available color. But keep in mind that if you have a palette full of
just black and white colors and you ask for bright red, you will most likely
get some sort of white (or gray) color, rather than red. Palette management is
outside of the scope of this document; see the <CITE>Texture Manager</CITE>
documentation instead.
</P><P>
To avoid hard-coding colors into the windowing system components do not draw
with `<SAMP>cs_Color_<VAR>XXX</VAR></SAMP>' constants. Instead, they just indicate the
index into the palette representing the color they wish to use. All standard
component palettes are contained in `<TT>cswspal.cpp</TT>' and `<TT>cswspal.h</TT>'.
</P><P>
There is no need to add your palettes to `<TT>cswspal.cpp</TT>'; that file is just
a convenience for standard windowing system components. Your components should
define their own palettes (if desired) and set the palette at startup (in the
constructor) using the <CODE>SetPalette()</CODE> method. Then you draw using palette
indices, just like standard CSWS components. It is strongly advised to
not use numerical indices for this, but instead define a set of macros of the
form `<SAMP><VAR>XX</VAR>PAL_<VAR>YYYY</VAR>_BACKGROUND</SAMP>',
`<SAMP><VAR>XX</VAR>PAL_<VAR>ZZZZ</VAR>_ACTIVETEXT</SAMP>' and so on; where <VAR>XX</VAR> is the short
name of your application (`<SAMP>CS</SAMP>' for `<SAMP>C</SAMP>'rystal `<SAMP>S</SAMP>'pace, `<SAMP>MZ</SAMP>'
for MazeD, the Maze Editor, and so on); <VAR>YYYY</VAR> and <VAR>ZZZZ</VAR> are the names
of the respective components, and the suffix gives the meaning of that palette
entry.
</P><P>
For illustration here are the palette indices for the standard CSWS
scroll bar palette:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>#define CSPAL_SCROLLBAR_BACKGROUND 0
#define CSPAL_SCROLLBAR_SELBACKGROUND 1
#define CSPAL_SCROLLBAR_DARK3D 2
#define CSPAL_SCROLLBAR_LIGHT3D 3
</pre></td></tr></table></P><P>
If you want to change a specific palette entry for a <EM>specific</EM> component,
you can use the <CODE>SetColor()</CODE> method. You should provide a index into the
target component's palette and a color (one of `<SAMP>cs_Color_<VAR>XXX</VAR></SAMP>'
constants defined above). For example, to set the background color for some
scrollbar to bright red, you can use the call:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>csScrollBar* sb; // Assume that this points at a scroll bar.
sb->SetColor(CSPAL_SCROLLBAR_BACKGROUND, cs_Color_Red_L);
</pre></td></tr></table></P><P>
<A NAME="CSWS Components"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_143.html#SEC311"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_145.html#SEC316"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_142.html#SEC310"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_143.html#SEC311"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_149.html#SEC326"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
This document was generated
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
|
