1Decorator class
2###############
3
4Decorators provide the actual drawing for a window's looks.
5
6\_ Indicates a protected member function
7
8Member Functions
9================
10
11Decorator(BRect int32 wlook, int32 wfeel, int32 wflags)
12-------------------------------------------------------
13
14Sets up internal variables common to all decorators.
15
161) Assign parameters to respective data members
17
18~Decorator(void)
19----------------
20
21Empty.
22
23void SetColors(color_set colors)
24--------------------------------
25
26void SetDriver(DisplayDriver \*driver)
27--------------------------------------
28
29void SetClose(bool is_down)
30---------------------------
31
32void SetMinimize(bool is_down)
33------------------------------
34
35void SetZoom(bool is_down)
36--------------------------
37
38void SetFlags(int32 wflags)
39---------------------------
40
41void SetFeel(int32 wfeel)
42-------------------------
43
44void SetLook(int32 wlook)
45-------------------------
46
47bool GetClose(void)
48-------------------
49
50bool GetMinimize(void)
51----------------------
52
53bool GetZoom(void)
54------------------
55
56int32 GetLook(void)
57-------------------
58
59int32 GetFeel(void)
60-------------------
61
62int32 GetFlags(void)
63--------------------
64
65void SetTitle(const char \*string)
66----------------------------------
67
68void SetFont(SFont \*sf)
69------------------------
70
71These functions work with the internal members common to all
72Decorators - assigning them and returning them. Additionally,
73SetTitle() and SetFont() set the clip_font flag to true.
74
75int32 \_ClipTitle(float width)
76------------------------------
77
78ClipTitle calculates how much of the title, in characters, can be
79displayed in the given width.
80
811. Call StringWidth() on the title.
822. If the string's width is less thanwidth, return the string's
83   character count
843. while the character count to display is > 0
85
86   a. calculate the string's width
87   b. if the string's width is less than width, return the character count
88   c. decrement the character count
89
904. If the loop completes itself without returning a value, it can't fit,
91   so return 0.
92
93void SetFocus(bool is_active)
94-----------------------------
95
96This is for handling color states when a window receives or loses the
97focus.
98
991. Set focus flag to whatever is_active is.
1002. call hook function \_SetFocus()
101
102bool GetFocus(void)
103-------------------
104
105Returns the focus state held by the decorator
106
1071) Return the focus flag
108
109int32 \_TitleWidth(void)
110------------------------
111
112Returns the character count of the title or 0 if it is NULL.
113
114Virtual Functions
115=================
116
117Most of these functions have a default behavior which can be
118overridden, but are implemented to handle the more common
119implementations.
120
121void MoveBy(float x, float y)
122-----------------------------
123
124void MoveBy(BPoint pt)
125----------------------
126
127Move all member rectangles of Decorator by the specified amount.
128
129void ResizeBy(float x, float y)
130-------------------------------
131
132void ResizeBy(BPoint pt)
133------------------------
134
135Resize the client frame, window frame, and the tab frame (width only)
136by the specified amount. Button rectangles - close, minimize, and zoom
137- are not modified.
138
139void Draw(BRect r)
140------------------
141
142void Draw(void)
143---------------
144
145Main drawing call which checks the intersection of the rectangle
146passed to it and draws all items which intersect it. Draw(void) simply
147performs drawing calls to draw the entire decorator's footprint area.
148
1491. Check for intersection with BRect which encompasses the decorator's
150   footprint and return if no intersection.
1512. Call \_DrawFrame(intersection)
1523. Call \_DrawTab(intersection)
153
154void DrawClose(void)
155--------------------
156
157protected: void \_DrawClose(BRect r)
158------------------------------------
159
160void DrawMinimize(void)
161-----------------------
162
163protected: void \_DrawMinimize(BRect r)
164---------------------------------------
165
166void DrawZoom(void)
167-------------------
168
169protected: void \_DrawZoom(BRect r)
170-----------------------------------
171
172Each of these is designed to utilize their respective button
173rectangles. The public (void) versions simply call the internal
174protected ones with the button rectangle. These protected versions
175are, by default, empty. The rectangle passed to them is the invalid
176area to be drawn, which is not necessarily the entire button's
177rectangle.
178
179void DrawFrame(void)
180--------------------
181
182protected: void \_DrawFrame(BRect r)
183------------------------------------
184
185Draws the frame, if any. The public version amounts to
186\_DrawFrame(framerect). The protected version is expected to not cover
187up the client frame when drawing. Any drawing within the clientrect
188member will end up being drawn over by the window's child views.
189
190void DrawTab(void)
191------------------
192
193protected: void \_DrawTab(BRect r)
194----------------------------------
195
196Draws the window's tab, if any. DrawTab() amounts to
197\_DrawTab(tabrect). If window titles are displayed, the \_DrawTitle
198call is expected to be made here. Button-drawing calls, assuming that
199a window's buttons are in the tab, should be made here, as well.
200
201void DrawTitle(void)
202--------------------
203
204protected: void \_DrawTitle(BRect r)
205------------------------------------
206
207These cause the window's title to be drawn. DrawTitle() amounts to
208\_DrawTitle(titlerect).
209
210void \_SetFocus(void)
211---------------------
212
213This hook function is primarily used to change colors used when a
214window changes focus states and is called immediately after the state
215is changed. If, for example, a decorator does not use OpenBeOS' GUI
216color set, it would change its drawing colors to reflect the change in
217focus.
218
219SRegion GetFootprint(void)
220--------------------------
221
222This returns the "footprint" of the decorator, i.e. the area which is
223occupied by the window which is is the border surrounding the main
224client rectangle. It is possible to have oddly-shaped window borders,
225like ellipses and circles, but the resulting performance hit would
226reduce the said decorator to a novelty and not something useable. All
227versions are to construct an SRegion which the border occupies. This
228footprint is permitted to include the client rectangle area, but this
229area must not be actually drawn upon by the decorator itself. The
230default version returns the frame which encompasses all other
231rectangles - the "frame" member which belongs to its window border.
232
233click_type Clicked(BPoint pt, int32 buttons, int32 modifiers)
234-------------------------------------------------------------
235
236Clicked() performs hit testing for the decorator, given input
237conditions. This function is required by ALL subclasses expecting to
238do more than display itself. The return type will cause the server to
239take the appropriate actions, such as close the window, get ready to
240move it, etc.
241
242
243BRect SlideTab(float dx, dy=0)
244------------------------------
245
246SlideTab is implemented only for those decorators which allow the user
247to somehow slide the tab (if there is one) along the window.
248Currently, only the horizontal direction is supported. It returns the
249rectangle of the invalid region which needs redrawn as a result of the
250slide.
251
252Exported C Functions
253====================
254
255extern "C" Decorator \*create_decorator(BRect frame, int32 wlook, int32 wfeel, int32 wflags)
256--------------------------------------------------------------------------------------------
257
258Required export function which simply allocates an instance of the
259decorator and returns it.
260
261extern "C" float get_decorator_version(void)
262--------------------------------------------
263
264This should, for now, return 1.00.
265
266Enumerated Types
267================
268
269click_type
270----------
271
272- CLICK_NONE
273- CLICK_ZOOM
274- CLICK_CLOSE
275- CLICK_MINIMIZE
276- CLICK_TAB
277- CLICK_MOVE
278- CLICK_MOVETOBACK
279- CLICK_MOVETOFRONT
280- CLICK_RESIZE
281- CLICK_RESIZE_L
282- CLICK_RESIZE_T
283- CLICK_RESIZE_R
284- CLICK_RESIZE_B
285- CLICK_RESIZE_LT
286- CLICK_RESIZE_RT
287- CLICK_RESIZE_LB
288- CLICK_RESIZE_RB
289
290