3 <TITLE>Rune Language Gfx library</TITLE>
6 <CENTER><H2><B>Rune Language Gfx library</B></H2></CENTER>
7 <CENTER><H3><B>(c)Copyright 2002-2014, Matthew Dillon</B></H3></CENTER>
9 <H2><B>(I) General overview of Gfx library</B></H2>
12 The <B>gfx</B> library is a core graphical support library for Rune. It
13 allows you to build and manage physical windows, hierarchically
14 manage virtual windows (frames) within physical windows, and objects
15 within frames. <B>gfx</B> also eases event processing and
16 supplies a number of graphics primitives. It does not supply high level
17 gadgets. For that you need the <B>gadgets</B> library.
19 Window and frame sizes can be fixed, relative to their parent, or weighted
20 for either or both coordinates, and may have minimum and maximum sizes.
21 Window resizing can be controlled for either coordinate. Both windows
22 and frames have the notion of a viewport. Refresh is handled by the
23 object model and object management is optimized for viewport applications
24 (e.g. browser, cad/cam, etc...). Only a direct color model is supported.
26 Object methods for event processing are available for mouse buttons,
27 movement, and keyboard action. A single coherent stream is supported and
28 gadgets can both steal and return events in the method actions.
31 <H2><B>(II) The <B>Pen</B> class</B></H2>
34 The <B>Pen</B> class controls drawing modes. You create a (shared) pen
35 and then set the frame to use it. You can change the pen at any time,
36 potentially effecting many frames.
38 <B>setRGB(int r, int g, int b);</B>
41 Set the red, green, and blue values. The default value is (-1, -1, -1)
45 <B>setRGBMask(int rmask, int gmask, int bmask);</B>
48 Set the red, green, and blue masks. The default mask is (-1, -1, -1)
52 <B>setMode(int mode);</B>
55 Set the rendering mode for this pen. The default rendering mode
58 <P>NONE - transparent (do not render)
59 <P>SET - set value bits within the mask
60 <P>AND - logically AND value bits within the mask
61 <P>OR - logically OR value bits within the mask
62 <P>XOR - logically XOR valud bits within the mask
66 <H2><B>(III) Graphics ops for the <B>Frame</B> class</B></H2>
68 <P><B>setPenA(Pen *pen);</B>
69 <BR><B>setPenB(Pen *pen);</B>
72 A frame may have two pens associated with it. Typically you create
73 a single set of pens and then share them across all of your frames.
75 <P><B>drawPoint(int dx, int dy);</B>
78 Draw a point at (dx, dy) using Pen A. The current coordinate
79 cursor will be set to (dx, dy).
81 <P><B>drawLine(int sx, int sy, int dx, int dy);</B>
84 Draw a line from (sx, sy) to (dx, dy) using Pen A. The current
85 coordinate cursor will be set to (dx, dy).
87 <P><B>drawLineTo(int dx, int dy);</B>
90 Draw a line from the current coordinate cursor to (dx, dy) using
91 Pen A. The cursor will be set to the new (dx, dy).
93 <P><B>drawRect(int sx, int sy, int dx, int dy);</B>
96 Draw a rectangle using Pen A. (sx, sy) and (dx, dy) specify the
97 corners. The current coordinate cursor is set to (dx, dy).
99 <P><B>fillRect(int sx, int sy, int dx, int dy);</B>
100 <BR><B>fillInnerRect(int sx, int sy, int dx, int dy);</B>
103 Draw a filled rectangle using Pen B as the fill. (sx, sy) and
104 (dx, dy) specify the corners. <B>fillInnerRect()</B> does the
105 same thing except it increments sx and sy and decrements dx and dy,
106 and deals with any degenerate situation. The current coordinate
107 cursor is set to (dx, dy).
110 <H2><B>(IV) Frame management methods (subclass Gfx.Frame)</B></H2>
112 <P><B>createFrame(Frame *parent);</B> (global method)
115 Create a new frame inside the specified parent. If <I>parent</I> is
116 NULL, a new window will be created. The new frame or window must
117 be mapped before it will be visible.
119 <P><B>deleteFrame();</B>
122 The specified frame and all sub-frames are deleted.
124 <P><B>mapFrame();</B>
127 Map a frame into the display. The frame will not actually be visible
128 unless the parent frame(s) are also mapped.
130 <P><B>unmapFrame();</B>
133 Unmap a frame, removing it from the display.
135 <P><B>setFrameLimits(int minw, minh, int maxw, int maxh);</B>
138 Set the frame's minimum and maximum width and height, in absolute
139 pixels. -1 indicates no change.
141 <P><B>setFrameRect(int w, int h);</B>
144 Set the frame's width and height. Positive numbers indicate
145 absolute pixel values. Negative numbers indicate a weighted width
146 or height. For example, if three frames are locked to each other
147 left-to-right and frame A and B have widths of -10 and frame C has a
148 width of -20, then frame A will take 25% of the width of the parent
149 frame, frame B will take 25%, and frame C will take 50%.
151 <P><B>injectEvent(Event *event);</B>
154 Inject an event into a frame. This method is typically NOT refined by
155 a subclass. It is responsible for locating the appropriate sub-frame
156 and calling injectEvent() on that. If there are no sub frames this
157 function calls receiveEvent() as appropriate.
159 <P><B>receiveEvent(Event *event);</B>
162 When a frame receives an event this method is called. This method is
163 typically NOT refined by a subclass. It is responsible for checking
164 the event against masks, calling the appropriate event method, breaking
165 events up, and dealing with the return code (whether to pass the
166 event up the chain or eat it).
169 <H2><B>(V) Frame event-related methods (subclass Gfx.Frame)</B></H2>
171 <P><B>frameExposed();</B>
174 This method is called when the frame is partially or fully exposed
175 after previously being hidden. Most objects simply call frameRefresh()
176 from this method but sometimes you will want to manage animations and
177 such, and this is how you do it. Events and focus cannot occur
178 until a frame is exposed.
180 <P><B>frameHidden();</B>
183 This method is called when the frame is completely hidden after
184 previously being partially or fully exposed. This call will be
185 blocked until all event focii are lost.
187 <P><B>frameRefresh();</B>
190 This method is called when a partially or fully exposed frame needs to
191 be refreshed. This method may be called a number of times throughout
192 the life of the frame but will only be called once frameExposed()
193 has occured, and will no longer be called after frameHidden() has
196 <P><B>disableFrame();</B>
199 You call this method when you want to disable a frame and all gadgetry
200 within that frame (i.e. grey it out). If you call super.disableFrame()
201 from your custom disableFrame(), the superclass function will ensure
202 that all event focii are lost prior to returning. This does not
203 prevent a frame from being exposed, hidden or refreshed, but it will
204 filter all events for the frame.
206 <P><B>enableFrame();</B>
209 You call this method when you want to enable a frame, restoring
210 gradgetry to whatever state they were in before. If you call
211 super.enableFrame() from your custom enableFrame() soft focii will
214 <P><B>setSoftFocus(int evmask);</B>
215 <BR><B>clearSoftFocus(int evmask);</B>
216 <BR><B>setHardFocus(int evmask);</B>
217 <BR><B>clearHardFocus(int evmask);</B>
220 Adjust the soft and hard focii for a frame. Note that soft focus will
221 often be set and cleared automatically as a side effect of mouse
222 movement, with or without a mouse click, depending on the user
223 preference for focus mode. Hard focus is typically set from your
224 event handlers. For example, if someone moves the mouse over a
225 button and holds the mouse button down you typically obtain hard
226 focus on mouse movement and its buttons for the duration of the
227 button being held down, preventing those events from reaching other
230 <P><B>hardKeyboardFocusEntered();</B>
233 This is called when someone (usually you) sets hard focus on keyboard
236 <P><B>hardKeyboardFocusReleased();</B>
239 This is called when someone (usually you) releases hard focus on keyboard
240 events. Hard focus can also be forcefully released if another frame
241 steals the hard focus.
243 <P><B>hardMouseFocusEntered();</B>
246 This is called when someone (usually you) sets hard focus on mouse
249 <P><B>hardMouseFocusReleased();</B>
252 This is called when someone (usually you) releases hard focus on mouse
253 events. Hard focus can also be forcefully released if another frame
254 steals the hard focus.
256 <P><B>mouseEntered(int x, int y);</B>
259 The mouse has entered the object. You are given soft-focus on the
260 mouse until the mouse exits the objects. If you want to hold onto
261 the focus (for example, if a mouse button is pressed), you must
262 obtain hard focus on the mouse. While holding hard or soft focus
263 on the mouse you will, unless you block it, receive mouseMoved()
264 and mouseButton() events.
266 You are also given soft-focus on the keyboard with this event. However,
267 you may not receive any key events if someone else has hard-focus on
268 the keyboard. You must explicitly obtain hard-focus on the keyboard
269 to receive key events.
271 <P><B>mouseMoved(int x, int y);</B>
274 The mouse has moved while in the frame. Note that you will always
275 receive a mouseMoved() event just after a mouseEntered() event and
276 just before a mouseExited() event with the same coordinates as the
277 mouseEntered() or mouseExited() event.
279 <P><B>mouseExited(int x, int y);</B>
282 The mouse has entered the object and your soft-focus goes away.
283 However, you may still receive mouseMoved() and mouseButton() events,
284 as well as additional mouseEntered() and mouseExited() events
285 if you hold the hard focus.
287 Your soft keyboard focus will also go away, with the same provisio.
288 You may still receive keyPressed() events if you hold the hard keyboard
291 <P><B>keyPressed(int code, int mask);</B>
294 Keyboard events occur while you hold soft focus on the keyboard and
295 nobody else holds a hard focus, or while you hold hard focus on the
296 keyboard. Meta keys like control, caps lock, shift, and alt keys,
297 produce appropriate code events and the mask will reflect the addition
298 of the meta key in question.
300 If you lose the keyboard focus you will still receive keyReleased()
301 events as they occur. XXX
303 <P><B>keyReleased(int code, int mask);</B>
306 Key released. As with keyPressed() events, you get these when you hold
307 soft focus on the keyboard and nobody else holds a hard focus, or while
308 you hold hard focus on the keyboard. Meta keys like control, caps
309 lock, shift, and alt keys, produce appropriate code events and
310 the mask will reflect the removal of the meta key in question.
312 <P><B>setFocus(int code, int mask);</B>
313 <BR><B>addFocus(int code, int mask);</B>
314 <BR><B>delFocus(int code, int mask);</B>
318 <P><B>setFilter(int code, int mask);</B>
319 <BR><B>addFilter(int code, int mask);</B>
320 <BR><B>delFilter(int code, int mask);</B>
325 block events verses passing them on?
327 <P><B>addEventMask(int code, int mask);</B>
330 Add bits to the mask of events being caught.
332 <P><B>clearEventMask(int code, int mask);</B>