docs/gfx.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>Rune Language Gfx library</TITLE>
   4 </HEAD>
   5 <BODY>
   6 <CENTER><H2><B>Rune Language Gfx library</B></H2></CENTER>
   7 <CENTER><H3><B>(c)Copyright 2002-2014, Matthew Dillon</B></H3></CENTER>
   8 <P>
   9 <H2><B>(I) General overview of Gfx library</B></H2>
  10 <UL>
  11     <P>
  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.
  18     <P>
  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.
  25     <P>
  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.
  29     <P>
  30 </UL>
  31 <H2><B>(II) The <B>Pen</B> class</B></H2>
  32 <UL>
  33     <P>
  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.
  37     <P>
  38     <B>setRGB(int r, int g, int b);</B>
  39     <UL>
  40         <P>
  41         Set the red, green, and blue values.  The default value is (-1, -1, -1)
  42         (white).
  43     </UL>
  44     <P>
  45     <B>setRGBMask(int rmask, int gmask, int bmask);</B>
  46     <UL>
  47         <P>
  48         Set the red, green, and blue masks.  The default mask is (-1, -1, -1)
  49         (all bits).
  50     </UL>
  51     <P>
  52     <B>setMode(int mode);</B>
  53     <UL>
  54         <P>
  55         Set the rendering mode for this pen.  The default rendering mode
  56         is SET.
  57         <UL>
  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
  63         </UL>
  64     </UL>
  65 </UL>
  66 <H2><B>(III) Graphics ops for the <B>Frame</B> class</B></H2>
  67 <UL>
  68     <P><B>setPenA(Pen *pen);</B>
  69     <BR><B>setPenB(Pen *pen);</B>
  70     <UL>
  71         <P>
  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.
  74     </UL>
  75     <P><B>drawPoint(int dx, int dy);</B>
  76     <UL>
  77         <P>
  78         Draw a point at (dx, dy) using Pen A.  The current coordinate
  79         cursor will be set to (dx, dy).
  80     </UL>
  81     <P><B>drawLine(int sx, int sy, int dx, int dy);</B>
  82     <UL>
  83         <P>
  84         Draw a line from (sx, sy) to (dx, dy) using Pen A.  The current
  85         coordinate cursor will be set to (dx, dy).
  86     </UL>
  87     <P><B>drawLineTo(int dx, int dy);</B>
  88     <UL>
  89         <P>
  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).
  92     </UL>
  93     <P><B>drawRect(int sx, int sy, int dx, int dy);</B>
  94     <UL>
  95         <P>
  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).
  98     </UL>
  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>
 101     <UL>
 102         <P>
 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).
 108     </UL>
 109 </UL>
 110 <H2><B>(IV) Frame management methods (subclass Gfx.Frame)</B></H2>
 111 <UL>
 112     <P><B>createFrame(Frame *parent);</B> (global method)
 113     <UL>
 114         <P>
 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.
 118     </UL>
 119     <P><B>deleteFrame();</B>
 120     <UL>
 121         <P>
 122         The specified frame and all sub-frames are deleted.
 123     </UL>
 124     <P><B>mapFrame();</B>
 125     <UL>
 126         <P>
 127         Map a frame into the display.  The frame will not actually be visible
 128         unless the parent frame(s) are also mapped.
 129     </UL>
 130     <P><B>unmapFrame();</B>
 131     <UL>
 132         <P>
 133         Unmap a frame, removing it from the display.
 134     </UL>
 135     <P><B>setFrameLimits(int minw, minh, int maxw, int maxh);</B>
 136     <UL>
 137         <P>
 138         Set the frame's minimum and maximum width and height, in absolute
 139         pixels.  -1 indicates no change.
 140     </UL>
 141     <P><B>setFrameRect(int w, int h);</B>
 142     <UL>
 143         <P>
 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%.
 150     </UL>
 151     <P><B>injectEvent(Event *event);</B>
 152     <UL>
 153         <P>
 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.
 158     </UL>
 159     <P><B>receiveEvent(Event *event);</B>
 160     <UL>
 161         <P>
 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).
 167     </UL>
 168 </UL>
 169 <H2><B>(V) Frame event-related methods (subclass Gfx.Frame)</B></H2>
 170 <UL>
 171     <P><B>frameExposed();</B>
 172     <UL>
 173         <P>
 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.
 179     </UL>
 180     <P><B>frameHidden();</B>
 181     <UL>
 182         <P>
 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.
 186     </UL>
 187     <P><B>frameRefresh();</B>
 188     <UL>
 189         <P>
 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
 194         occured.
 195     </UL>
 196     <P><B>disableFrame();</B>
 197     <UL>
 198         <P>
 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.
 205     </UL>
 206     <P><B>enableFrame();</B>
 207     <UL>
 208         <P>
 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
 212         be restored.
 213     </UL>
 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>
 218     <UL>
 219         <P>
 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
 228         frames.
 229     </UL>
 230     <P><B>hardKeyboardFocusEntered();</B>
 231     <UL>
 232         <P>
 233         This is called when someone (usually you) sets hard focus on keyboard
 234         events.
 235     </UL>
 236     <P><B>hardKeyboardFocusReleased();</B>
 237     <UL>
 238         <P>
 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.
 242     </UL>
 243     <P><B>hardMouseFocusEntered();</B>
 244     <UL>
 245         <P>
 246         This is called when someone (usually you) sets hard focus on mouse
 247         events.
 248     </UL>
 249     <P><B>hardMouseFocusReleased();</B>
 250     <UL>
 251         <P>
 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.
 255     </UL>
 256     <P><B>mouseEntered(int x, int y);</B>
 257     <UL>
 258         <P>
 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.
 265         <P>
 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.
 270     </UL>
 271     <P><B>mouseMoved(int x, int y);</B>
 272     <UL>
 273         <P>
 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.
 278     </UL>
 279     <P><B>mouseExited(int x, int y);</B>
 280     <UL>
 281         <P>
 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.
 286         <P>
 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
 289         focus.
 290     </UL>
 291     <P><B>keyPressed(int code, int mask);</B>
 292     <UL>
 293         <P>
 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.
 299         <P>
 300         If you lose the keyboard focus you will still receive keyReleased()
 301         events as they occur. XXX
 302     </UL>
 303     <P><B>keyReleased(int code, int mask);</B>
 304     <UL>
 305         <P>
 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.
 311     </UL>
 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>
 315     <UL>
 316         <P>
 317     </UL>
 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>
 321     <UL>
 322         <P>
 323     </UL>
 324
 325         block events verses passing them on?
 326
 327     <P><B>addEventMask(int code, int mask);</B>
 328     <UL>
 329         <P>
 330         Add bits to the mask of events being caught.
 331     </UL>
 332     <P><B>clearEventMask(int code, int mask);</B>
 333     <UL>
 334         <P>
 335     </UL>
 336 </UL>
 337 </BODY>
 338 </HTML>