
documentation
full reference
including
creating
handling
fields
example
designs
infos

|
this is a introduction to sgx which explains the general mechanics. after this you might want to see the examples in the directory 'sgxDoc\'.
further there is a full reference (sgxDoc\sgxDocFull.html and a smaller reference (sgxDoc\sgxDoc.html) without sgx internals. the file
_README.TXT in the base directoy contains further informations such a description of files and directories.
for an on-screen demo see 'demo.exe' and maybe 'testFPS.pb'.
including sgx
first you would probalby simply include the single-file version of sgx
XIncludeFile "sgx.pbi"
or the multi-file version
XIncludeFile "sgx_.pbi" ; will include all the other sgx_* files
the examples in the directory 'sgxDoc\' use a separate file ('_sgx_includer.pbi') to make it easier to switch between the two versions
for all examples.
alternatively you could also just duplicate the sgx.pbi to let's say my_sgx.pb and start coding at the end of the file. that way, if you
only use the design "lowbudget", this file would not have any dependencies for other include files or image files!
so you need at least the single sgx.pbi (or alternatively the sgx_* files). if you want to use designs other than "lowbudget" you would
additionally need the directory containing the design images. you can use the script 'make.bat' to recreate a single-file version package in
the directory 'sgx_build\', which only contains the files needed to simply use sgx (without tools and gimp files etc.). see _README.TXT
for details.
a note about autocompletion:
autocompletion of sgx element structure fields works best with the multi-file version (if 'sgx_access.pbi' is not part of the project and not
open in the editor). if you want to get complete autocompletion with the single-file version you may have to extract the sgx_access part and
put it in a separate file.
after you opened a screen you must call sgxLoadDesign() at least once to initalize sgx.
it returns a handle to the loaded design.
; load a design from disk
mydesign1 = sgxLoadDesign(".\sgxDesigns\grey")
; "lowbudget" loads from a datasection
mydesign2 = sgxLoadDesign("lowbudget")
"lowbudget" does not need any image files and can have any color. some other designs come as files with the package.
the last loaded design is used for new sgx objects, which you can create now.
you can change the currently used design by calling sgxSetDesign(mydesign).
sgxCursor(1)
sgxButton(2, 20,20, 100,25, "quit")
sgxSetDesign(mydesign1)
sgxButton(3, 20,50, 100,25, "button")
here 1, 2 and 3 are your choosen constant IDs of your sgx elements. if you want dynamic IDs then use -1 and catch the return value
mybutton = sgxButton(-1, 20,20, 100,25, "toggle me", #sgxStateOff)
some sgx element types (like windows) can have childs. so you must call sgxCloseLevel()
to create top-level objects again (or objects of the previous parent level). elements created in this block will automatically become
childs of the window.
sgxWin(4, 100,100, 200,180, "a window")
sgxButton(5, 10,30, 80,20, "child")
sgxCloseLevel()
you can add a tooltip to any object (in this case a constant has been used to create the element).
sgxTip(#buttonQuit,"exit"+#LF$+"demo")
note that this does not create a 'tip' element but rather sets a tooltip for our button element with the ID #buttonQuit.
in your main loop use sgxExamine() to process user actions
and sgxDisplay() to dispay the gadgets.
sgxExamine()
; ...
sgxDisplay()
you access your elements by ID and you can detect valid objects by a nonzero value of the macro sgx(id):
If sgx(2)
Debug "id=2 is an existing and valid sgx object"
EndIf
you can inquire states of objects by fields:
If sgx(2)\leftclick
quit = 1
EndIf
those field accesses must only be applied with valid IDs
here are some commonly used fields. for details see the documentation of the gadget structure sgxS_GADGET.
sgx(id)\leftclick ; single fired event for mouse button click
sgx(id)\rightclick ;
sgx(id)\leftdown ; continuously fired event for mouse button down
sgx(id)\rightdown ;
sgx(id)\leftup ; single fired event for mouse button release
sgx(id)\rightup ;
sgx(id)\lefthold ; hold event fired in intervals
sgx(id)\state ; the current state of a checkbox or a scrollbar/trackbar etc (see structure description).
sgx(id)\text ; a window's title, button's caption, edit's content, etc.
sgx(id)\type ; a value of one of the #sgxType.. constants
sgx(id)\show ; if #True then the element will be displayed and receives events, otherwise #False.
sgx(id)\disabled ; 0 by default. 1 if the element is currently disabled.
sgx(id)\hover ; continuously fired event if the mouse is hovering the element
sgx(id)\changed ; single fired event if the element's state or the text/textpos of an sgxEdit etc. has changed.
sgx(id)\resized ; single fired event if the size has changed
(you may have to adapt the path in the include statement and in the second call of sgxLoadDesign())
XIncludeFile "sgx.pbi"
InitSprite()
InitMouse()
InitKeyboard()
win = OpenWindow(0, 1,1, 800,600, "..", #PB_Window_ScreenCentered)
OpenWindowedScreen(win, 0,0, 800,600)
; define some element IDs (always start with id 1)
Enumeration 1
#cursor
#buttonQuit
#window
#buttonChild
EndEnumeration
; load some designs. "lowbudget" can have any color.
design1 = sgxLoadDesign("lowbudget", RGBA($88,$66,$00,$dd))
design2 = sgxLoadDesign("sgxDesigns\grey")
If Not (design1 And design2)
MessageRequester("error","can't load designs") :: End
EndIf
; create two elements
sgxCursor(#cursor)
sgxButton(#buttonQuit, 20,20, 100,25, "quit")
; change the design
sgxSetDesign(design1)
; create some other elements
mybutton = sgxButton(-1, 140,20, 100,25, "toggle button", #sgxStateOn)
sgxWin(#window, 100,100, 300,180, "a window")
sgxButton(#buttonChild, 10,30, 100,20, "child element")
sgxCloseLevel()
; add a tooltip to the quit button
sgxTip(#buttonQuit, "exit"+#LF$+"demo")
Repeat
ExamineMouse()
ExamineKeyboard()
; proccess PB window events
Repeat
event = WindowEvent()
If even = #PB_Event_CloseWindow
quit = #True
EndIf
Until Not event
; update sgx events
sgxExamine()
; process sgx events
If sgx(#buttonQuit) And sgx(#buttonQuit)\leftclick
quit = #True
EndIf
; display all sgx elements
sgxDisplay()
FlipBuffers()
ClearScreen($002222)
Delay(5)
Until quit Or KeyboardPushed(#PB_Key_Escape)
a design has a directory containing some image files.
for example: '..\sgxDesigns\outdoor'
- BackgroundHover.png
- BackgroundNormal.png
- MouseCursor.png
- parts.png
the background pictures will be tiled to fill the areas they are drawn onto. 'MouseCursor' will be used for sgx elements of type #sgxTypeCursor.
'parts' contains the border images (4 corners and 4 sides for each state: normal, hover and pushed), and also the 2 states for the close buttons
of windows (normal and hover) as well as the part displayed for checked checkboxed. the color found in the upper left corner
(pixel 0,0) will be interpreted as to be used to seperate the elements in this image. the color found in the bottom
left corner (pixel 0,imageHeight-1) will be the base-color of the design if nothing else is specified at
sgxLoadDesign(). the elements should be more or less in order, separated by at least 1-pixel-thick
rows and columns in the separating color. the images as well as the elements in the parts
image can be of any size.
..\sgxDesigns\outdoor\parts.png (magnified) :
here is a quick list of usefull variables and macros/functions
|