Main Page | Namespace List | Class Hierarchy | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

CSLib.cpp

Go to the documentation of this file.
00001 /*! \page cslib1 Concept of CSLib 
00002   \section cslibutilis1 Concepts & Style
00003 
00004   \subsection cslibutilisdebug1 Logging
00005   <UL>
00006       <LI> 
00007         Log
00008       </LI> 
00009   </UL>
00010 
00011   \subsection cslibutilisloading1 Loading globally!
00012   <UL>
00013       <LI> 
00014         Loadable
00015       </LI> 
00016   </UL>
00017 
00018   \subsection cslibutilisxml1 XML & XPath
00019   <UL>
00020       <LI> 
00021         XML
00022       </LI> 
00023       <LI> 
00024         XPATH
00025       </LI> 
00026   </UL>
00027 
00028   \subsection cslibutilismessage1 Messaging
00029   <UL>
00030       <LI> 
00031         Log
00032       </LI> 
00033   </UL>
00034 
00035   \section cslibgame1 CSGame
00036   \subsection cslibgamegraphic1 Graphics and Animations
00037   <UL>
00038       <LI> 
00039         Sprites
00040       </LI> 
00041       <LI> 
00042         Actions
00043       </LI> 
00044       <LI> 
00045         Animations
00046       </LI> 
00047       <LI> 
00048         Pictures
00049       </LI> 
00050   </UL>
00051 
00052   \subsection cslibgamesound1 Music & Samples
00053   <UL>
00054       <LI> 
00055         Music
00056       </LI> 
00057       <LI> 
00058         Samples
00059       </LI> 
00060   </UL>
00061 
00062   \subsection cslibgameworld1 World & Tile
00063   <UL>
00064       <LI> 
00065         World
00066       </LI> 
00067       <LI> 
00068         Tilemap
00069       </LI> 
00070       <LI> 
00071         Tileset
00072       </LI> 
00073       <LI> 
00074         Tile
00075       </LI> 
00076   </UL>
00077 
00078   \subsection cslibgametext1 Fonts and printing
00079   <UL>
00080       <LI> 
00081         Font
00082       </LI> 
00083   </UL>
00084 
00085   \section cslibgui1 GUI
00086   \subsection cslibguielement3 GraphicElement
00087   <UL>
00088       <LI> 
00089         GraphicElement
00090       </LI> 
00091       <LI> 
00092         Desktop
00093       </LI> 
00094       <LI> 
00095         other elements
00096       </LI> 
00097       <LI> 
00098         Layout (adding, removing, autosizing)
00099       </LI> 
00100   </UL>
00101   \subsection cslibguielement2 LAF
00102   \subsection cslibguielement1 Messages
00103 
00104 */
00105 
00106 
00107 /*! \page gui1 GUI and screen updates
00108     The GUI wihtin this library assumes, that befor each "update round" the complete
00109     area ist blanked.
00110 
00111     For an example how the gui should be updated see the folloing code (from \a CSGame):
00112     <PRE>
00113     while (!mQuit)
00114     {
00115         do
00116         {
00117             handleEvents();
00118             if (mPause)
00119             {
00120                 SDL_Delay(50);
00121             }
00122         }
00123         while ((mPause) && (!mQuit));
00124 
00125         if (mIsGui)
00126         {
00127             SDL_Rect area;
00128             area.x = 0;
00129             area.y = 0;
00130             area.w = SDLMain::getScreenWidth();
00131             area.h = SDLMain::getScreenHeight();
00132             mDesktop->paint(SDLMain::getScreen(), 0);
00133             SDLMain::updateScreen();
00134             SDL_FillRect(SDLMain::getScreen(), &area, COLOR(SDLMain::getScreen(), 0));
00135             SDLMain::addUpdateRect(area);
00136             mDiffTimeGUI = SDL_GetTicks() - desktopDrawStart;
00137         }
00138         // .. draw non gui stuff at the background of the gui e.g. the game
00139     }
00140     </PRE>
00141     That also means that each and every gui component is drawn at each update!
00142     There are some (good ones, I think) reasons for this:
00143     \arg Computers are now easliy able to do it, they are fast enough!
00144     \arg It saves all the trouble one has in keeping in mind which things to update,
00145          which backgrounds to save, redrawing stuff under the mouse-cursor etc...
00146     \arg <i>This library was intended this way.</i> It was started of as a means to
00147          create a user frontend for "in game" communication. That also implies the
00148          possiblity for the game to continue while changing stuff with the gui.
00149          The gui itself does not <b>know</B> anything about any game! So it wouldn't
00150          know which areas to update! <b> And </b> the game doesn't know about the gui
00151          either!
00152     \arg Again - it makes the whole screen updating very simple!
00153          (Believe me! I once wrote a gui library, that only updated areas of the screen
00154           where changes occured, including keeping track of game information, it was 
00155           an updating horror, for people interested, look at the gui of the DOS Vectrex
00156           emulator, that's the gui I'm talking about. But at the time I wrote that gui,
00157           it was neccessary, computers were not fast enough (or I was a bad programmer :-)))
00158 */
00159 
00160 /*! \page gui2 Concept of the CSLib GUI
00161     The GUI of CSLib is based one single class <B>CSGrafikElement</B>.
00162     This class is the base class of all other elements, widgets, windows, desktop and other entities.
00163     The base class keeps track of position, sizing and the like.
00164     Also it provides mechanisms for painting and string output and LAF support and children (other CSGrafikElement elements).
00165     For a complete list of features and supporting methods see \a CSGrafikElement.
00166 
00167     \section structuregraphicelement  GraphicElement Structure
00168     Each CSGraphicElement constists of:
00169     \arg an area (CSArea)
00170     \arg and its children (or direct paint directives)
00171     \arg a border (CSBorder)
00172 
00173     During each painting of a GraphicElement these are drawn on screen in the above order.
00174     Usually the area and the border are determined by the currently set LAF. But one
00175     can set elements their own special version, the own area's and border's must fullfill
00176     the interface defined in the classes \a CSBorder and \a CSArea.<BR>
00177 
00178     \section structuregraphicelementborder Borders
00179     As of now their are two different types of borders.
00180     \arg CSBorder (a normal rectangular border with shades)
00181     \arg CSRoundedBorder (as above but with rounded corners)
00182 
00183     One can define own borders, which (as a thought) include animations, changing colors
00184     or the like.
00185 
00186     \section structuregraphicelementarea Areas
00187     As of now their are several different types of areas.
00188     \arg CSArea (a normal rectangular area with)
00189     \arg CSRoundedArea (as above but with rounded corners)
00190     \arg CSGradientArea (a rectangular area, with two differnt colors, 
00191          which gradually change from one to the other), horizontally or vertically
00192     \arg CSPictureArea, which takes a picture as the "background" of an element, stretched, or centered
00193     
00194     One can define own areas, which (as a thought) include animations, changing colors
00195     or the like.
00196 
00197     \section structuregraphicelementchildren Children
00198     Each \a GraphicElement can take a(ny) number of GraphicElements as children. Children
00199     can be arranged via a CSLayoutManager. 
00200     \arg CSLayoutManagerXY
00201     \arg CSLayoutManagerBorder (north, south, east, west, center)
00202     \arg CSLayoutManagerStack (horizontally, and vertically)
00203 
00204     elements added to another element can have different options:
00205     \arg autosizing (horizontally, vertically, both)
00206     \arg viewported 
00207     \arg centered
00208     \arg space (between itself and other elements)
00209 
00210     \section structuregraphicelementmessage Messages
00211     If something happens -> a message is passed to everyone who is interested.
00212     A listener can be added to each element. The message that is sent will be of
00213     the type \a CSMessage in special \a GuiMessage.<BR>
00214     
00215     \section structuregraphicelementmessageinternal Internal Messages
00216     The receiver of Gui-driven events (mouse movement, clicks, etc) will allways be
00217     the element that is furthest down the element hierachie.<BR>
00218     e.g.<BR>
00219     The desktop has a window, the window has a panel, which has a button. 
00220     If the mouse is hovering above the button and the user clicks the (mouse) button.
00221     The CSButton, which is part of the panel, which is part of the window... receives 
00222     a \a MOUSE_BUTTON_PRESSED_MESSAGE - message. The innermost element is responsible for
00223     the message. If it not interested in it, it should pass the message on to
00224     it's parent - element (one up in the hierachy)!
00225 
00226 
00227 
00228 
00229 */
00230 
00231 /*! \page gui3 Viewported versus not Viewported
00232     Every grafical element has a size, internally they are called <TT>mWidth</TT> and <TT>mHeight</TT>.
00233     
00234     E.g. a window constructed with <TT>new CSWindow(200, 400)</TT> has a height of
00235     200 and a width of 400. This is space the window occupies on the screen
00236     (if not out of bounds).
00237     <P>
00238     (The following text refers to windows only, since windows are easy to understand,
00239      but the viewport concept holds true for <b>ALL</B> CSGraphikElements.)</P>
00240 
00241     The maximum size of the viewport of the window is at this moment also 200 x 400
00242     (that doesn't imply, that all elements added to the window are size restricted to 
00243      be smaller than 200 x 400 -> but that later).
00244     
00245     The viewport of the window is the hole, thru that a spectator can watch the action
00246     that takes place behind the window.
00247     A real life example, take a window: a <b> REAL </B> window - out of glass.
00248     What makes up the window? Say you see it from two meters distant.
00249     \arg the glass, thru that you can see the kids playing in the garden
00250     \arg the window frame (plastic, or wood?)
00251     \arg a handle to open/close the window
00252 
00253     This example has everything in it a computer window needs. Here the translation:
00254     \arg glass <-> viewport 
00255     \arg frame <-> borders and titlebar
00256     \arg handle <-> buttons and icons for sizing, menu
00257 
00258     The viewport is the part of the window "thru" which you can see elements of the 
00259     window.
00260     With this example you see that there are defenitly elements of a window, that
00261     don't reside in the viewport.
00262     Elements that usually <B>are not</B> viewported:
00263     \arg titlebar 
00264     \arg menubar
00265     \arg borders
00266     \arg closebuttons 
00267     \arg scrollbars 
00268     \arg etc.
00269 
00270     Elements that usually <B>are</B> viewported:
00271     \arg textfields 
00272     \arg buttons (ordinary)
00273     \arg textarea
00274     \arg html-output 
00275     \arg combobox
00276     \arg etc.
00277 
00278     The viewport is (nearly all the time) smaller than the window size.
00279     Internally the size is kept in <TT>mViewportHeight</TT> and <TT>mViewportHeight</TT>.
00280     The viewport has an offset to the position of the window start 
00281     (kept in <TT>mViewportX</TT> and <TT>mViewportY</TT>).
00282 
00283     Non viewported elements are usually autosizing (menubars stretch all the way, even
00284     if the size of the window changes). If they are not autosizing, it is assumed they
00285     don't influence the viewport size! -> \sa CSGrafikElement::buildArea()
00286     
00287       The size of the viewport is changed, when adding non viewported elements (since the size
00288     of the window does not change).
00289 
00290     When adding a viewported element, the position of the element is in relation to the
00291     viewport start. That means you cannot position a viewported element on the window
00292     on a position that is not taken up by the viewport. The window thinks it
00293     belongs to the viewport and is actually displaying only parts of it if positioned out of bounds
00294     (like -> you don't see the whole sky if you look out of the real window, only part of it).
00295 
00296     When adding elements to a window that are not viewported, they are in relation 
00297     to the actual start position of the window.
00298 
00299     All elements can either be viewported or non viewported. <B> Befor</B> they are
00300     added to another element, they must be set to either viewported or non viewported, using:
00301     <PRE>
00302             void setViewported(bool viewported) 
00303     </PRE>
00304     All elements have sensible default values!
00305 */
00306 
00307 
00308 /*! \page gui4 Structure of Grafikal Elements
00309     
00310 */
00311 
00312 
00313 
00314 
00315 

Generated on Wed Jul 14 00:43:30 2004 for CSLib by doxygen 1.3.6