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